-
-
Notifications
You must be signed in to change notification settings - Fork 150
The endpoints are described in OpenAPI 3.0 stored in YAML files. The choice for OpenAPI 3.0 is determined by the fact that we use JSONSchema::Validator which currently does not provide OAS 3.1 support (yet). The library which does support OAS3.1 support (JSON::Schema::Modern), imports Mojolicious, which is a full web framework that we currently don't depend on.
- Factor commonality into shared description
- Definition of response codes
- Factor out boiler plate from all APIs
- Generate documentation using OpenAPI 3.0 input files
- Definition of the use of filter criteria
- Definition of the interaction of resources with workflows
- [ ]
Web service requests currently support exactly one input media type: application/json. End points intended for file uploads accept a wide range of media types as an exception.
Incoming requests have the following validations applied:
- Maximum request body
- JSON errors
- Schema correctness (e.g. required fields)
- Functional correctness (e.g. existing (cross) references to data entities)
Each of these phases can generate one or more errors. Per phase, the server will determine as many errors as possible and report back all errors found.
Requests on existing resources will be managed for "idempotency" using ETag headers: Every response on an existing or created resource returns an ETag header which must be used by modifying (PUT/PATCH/POST) service calls to uniquely identify the resource version being modified. Creation requests are a different matter: since there is no resource yet, there's no ETag to be retrieved from the server in order to be able to send a modification request. The solution here is to add a "creation UUID" to each creation request. The server checks the creation UUID on each creation request against the UUIDs in the system. When there's a match, the submitted data is compared to the state of the existing resource. When the resource state matches (the definition of a match may be resource specific), the existing resource is returned. When the state does not match, an error 422 (Unprocessable request) is returned.