Evaluate the possibility of a no-code implementation as a file/directory

[mcupak]

A nice design consideration that came from the Search API is the ability to implement the specification by providing a static file (or a directory of files) on a web server, GitHub, or a cloud bucket. Having a fairly static list of public services is presumably very common for many organizations so we should see if our specification can be implemented this way.

[mcupak]

Going over the spec, I think we're pretty close. I think the only problems we have are the following:

1. Pagination problem.
   Right now, the client controls the pagination. For a file-based implementation, this would need to be controlled by the server, i.e. no query parameters for pages.

2. Endpoint names problem.
   For a file-based implementation, we need the endpoints to not conflict. In other words, /services needs to be a file, i.e. we can't have /services/types and /services/{serviceId}.

Possible solutions:

1. Pagination problem.
   1. Remove pagination and represent everything as a single file.
      Pros: Allows us to get rid of the contents wrapper of all elements, generally simpler.
      Cons: Not good for clients if anyone has too many services (is that a real use case?).
   2. Remove pagination query params and represent pages as different files. That means the server determines pagination links.
2. Endpoint names problem.
   1. Use /services for the main list, /service/* for other endpoints.
      Pros: Works.
      Cons: Doesn't respect usual REST conventions.

Is this worth doing?

[mcupak]

We've discussed this a bunch and didn't have a clear winner, so it seems we can't really go wrong with either option. I'd propose the following:

1. Drop pagination.
2. Don't change the endpoints.

The reason for 1 is that none of the current driver project implementations take advantage of pagination, and it pollutes the API. While our pagination is optional and sort of flexible, it might also conflict with how pagination is done elsewhere in the specs or their implementations extending the registry. It's unlikely anyone would have enough services to really need pagination. Even Google doesn't have pagination in their discovery service.

2 would prevent us from having a no-code implementation, but allows us to keep usual REST conventions. I think that's a reasonable level of future-proofing. For example, we might add CRUD endpoints later (#65), which would break this anyway. Also so far, noone had an issue implementing this as a service.

Does anyone have any objections?

[mcupak]

+1 from Andy.