Atomic Endpoints - Standardize query parameters (for example in Collections)

[joepio]

Some resources function like an endpoint: they accept (optional) query parameters which modify the response. A Collection, for example, might use a page parameter and a sortedBy parameter. These available query parameters and their datatypes might be standardized.

How should the client know if a certain resource has query parameters available? How do we communicate this?

One approach is to make all query parameters available as nested resources in an array, under some new property. Each parameter needs a shortname, a datatype (perhaps default to string), bool whether its optional...
We could also have to property URLs: requiredParams and optionalParams.

[joepio]

In Atomic, I have some logic named "Extended Resources", which deals with the logic above. When fetching any resource, the Classes are checked. If any of these match, a special function is called.

For example, if /classes is requested, the class Collection is matched and the construct_collection is called, which paginates the resource and gets the actual underlying values (the items for the Collection)

[joepio]

Have endpoint-specific properties

Say we open /versions in the browser. It defaults to a collection of the most recently made changes to all resources. But... it is a special collection, because it has some extra properties:

Things that an endpoint needs to describe:

• A list of parameters (= Properties)
• Description
• Shortname

Parameters need to describe:

• Whether they are optional or required
• What their required datatype is
• Shortname
• Description

Paramaters look a lot like Properties. It's probably a good idea to use these.

Collection or new Class?

There's a lot of overlap between Collections and Endpoints. Both have a bunch of query parameters, and in many (or all?) usecases, it makes sense to use the same params (pagination, sorting, filtering).

Or is a Collection (also) an Endpoint? That actually seems to make a lot of sense, since that fixes the whole discoverability issue of the query parameters. So does every instance of a Collection contain a optional-parameters with an array of filter, sort, etc.?

Multi Class

Say we look at some Collection. We could say that this is both an Endpoint and a Collection. The is-a attribute supports multiple classes for a reason. But this has some implications. For example, when rendering the view. Currently, I match the Classes in is-a and take the registered view for the first one that hits. We could change this to matching n classes for a view, so that we could have views for specific combinations of classes.

Of we could have a View switcher, that switches from one registered view to the next one. Would probably result in some sub-optimal UX in some cases.

[joepio]

Since posting the comments from above, I've actually implemented some endpoints and they can easily be used in the new front-end app. Here's how they work:

• Fetching an endpoint without any query parameters always returns an Endpoint resource.
• This resource has a bunch of Parameters, which provide the information to the client about how the endpoint works
• The client sets the parameters as query parameters, and gets that URL
• The server responds with... something that should make sense.

I've implemented a path endpoint, a version endpoint, and an all-versions endpoint.

There were also a couple of Endpoints that I wanted to do, but didn't because of the current limitations:

• I don't handle POSTS at this moment, which means that I can't handle bodies. This means that the /commit endpoint is not actually an Atomic Endpoint.
• I can't browse the pages on the all-versions endpoint, and fixing that seems both hard and hacky.
• The UX of responses is always kind of... Funky. I feel like the controls that I'm offered as an end user are not enough, and the fact that the form completely disappears after getting the response is also weird.

How can this be improved upon?

Always return Endpoints

Imagine gettings /all-versions&subject=somesubject. Instead of returning a collection, we could return the endpoint itself, which then has a reference to a result. That result can then contain the actual response, in this case a list of versions. In a different endpoint, in /path for example, result could be a Resource or an Atom Resource.

update: this is what I've used for /search