Dealing with /upload and /download - Support other HTTP methods in Endpoints

[joepio]

At this point, Endpoints exclusively use Query parameters for communicating something with the Server. This works great for things like Collections, but not for things like Uploading files. For the /upload endpoint in atomic-server, I simply implemented the mutli-part-form spec in the client and server. This means POSTing data, and putting binary data in the body. I'd like to standardize these types of APIs too. That way these API's too would become machine readable, which means I can do things like render forms for them.

Before diving into options, let's make a list of usecases that query params do not cover:

• Uploading data, which is done using multi-part forums and POST request.
• Downloading files, which do not return atomic-data JSON-AD responses, but can return any file with any mimetype.
• TPF endpoint, because it does something weird when serializing to RDF: it simply returns the individual triples, not a 'collection' or something. But let's be honest - the usecase for this is hard to make now that we've got Collections that support TPF queries, too.
• /pictures, an endpoint that will return / resize photos. The input could be query params, but the output is not JSON-AD.

Candidate properties for Endpoints

• method - This could be set to POST, for example. If not set, the client will use GET or use WebSockets.
• mime-response - Mimetype of the response. If not set, will assume JSON-AD.
• mime-request - Mimetype of the request. If not set, will assume JSON-AD. Will be multipart/form-data for example.
• form-requires - fields required in the form body. Similar to https://atomicdata.dev/properties/requires
• form-recommends - fields required in the form body. Similar to https://atomicdata.dev/properties/recommends
• post-params - similar to parameters, but for bodies. If specified POST needs to be a JSON-AD object with the properties present in post-params.
• supported-methods - required property, GET or POST possible.

Designs

Split up GET and POST endpoints in two Classes

• Two different endpoint classes, two types of behavior
• Semantically / HTTP correct. Also means things like proxies and caching know that GET is idempotent and POST is not.
• Can be constraining - what if you want to POST a JSON body for a Query (e.g. elasticsearch / graphql)
• What if the user wants to support both a body and query params?

Hybrid usage - allow both GET and POST to be used interchangably

• You can POST a JSON body containing the query parameters
• Some fields can never be put in a URL, like byte streams, or things of more than 1024 characters.
• Not valid HTTP, as now some GET requests will write resources, which means its not idempotent. And some POST requests will not mutate anything (like they do in GraphQL and elastic, btw)

Add uploadDescription property to Endpoints

• If this is set, the endpoint needs to support POST requests
• The behavior is entirely up to the implementation of the Endpoint
• The endpoint handler just receives a stream of bytes
• You can still parse query parameters using parameters