This document is a proposed specification for the deployment APIs that consultation service providers will be required to develop for allowing the French consultations portal to implement a "one-click instant deploy".
- the "platform": the French consultations portal platform ;
- the "provider(s)": the SaaS consultation provider service(s).
Allowing a smooth yet secure deployment requires a symetric set of APIs:
- one part must be run and maintained by the service provider (Cap Collectif for instance, among others) ;
- the other part must be run by the platform, to collect feedback and informations from the service providers.
This specification emphazises the "providers" part, but also gives some hints on the "platform" side:
- provider.swagger.yml lists the minimal set of APIs that should be exposed by the providers ;
- platform.swagger.yml lists the minimal set of APIs that should be exposed by the platform.
Some design principles:
- These APIs communicate over http2 or https (with valid certs) ;
- At first, API security will be handled through shared secrets (one secret per provider, no OAuth nor JWT). This approach should change after the first launch of the whole platform ;
- Some solutions may require
spf
andDKIM
dns entries to be created ; - it is strongly recommended that each solution will only be available to users through
https
, using an automated certification authority (eg. Let's Encrypt which is free and open). This, however, requires that DNS entries are created (and flushed) before the instance creation request is issued. Details in the chapter "Deployment Workflow" below ;
The basic deployment workflow includes several steps:
- 1- a user requests a
example.consultation.gouv.fr
instance on the platform website. His request is (email) verified, rate-limited and, if it seems legitimate, the instance creation process is launched ; - 2- the platform creates the DNS entries, depending on the requirements of the provider:
- a
CNAME
dns entry is created, which linksexample.consultation.gouv.fr
to a DNS name given by the provider. This supposes that all the consultation platforms created through this API will hit the very same front server - which is BAD for scalability. An improved version should allow the provider to change the CNAME target for each instance through an API (as long as the default CNAME target) - if required by the provider,
SPF
andDKIM
entries have to be created for@example.consultation.gouv.fr
. All the outgoing emails will be sent using ano-reply@example.consultation.gouv.fr
email address.
- a
- 3- the provider's
/instances
creation endpoint is called by the platform, which then displays an informative message to the user ; - 4- the provider deploys the instance - this is done synchronously or asynchronously, and the platform will get an appropriate status code. Once completed, the deployment status and metadata are sent to the platform's
/instances/{requestIdentifier}
endpoint using http'sPATCH
method. The "metadata" is a flat key-value array, which may contain several informations that the provider could find interesting to communicate to the platform (admin interface url, admin username, admin password, instance creation duration, http authentication credentials, etc.)
Additional instance-lifecycle management operations have not been documented using this workflow but could be useful in the future. Here are some ideas:
- request the termination/archive of an instance (with a cancellation delay?) ;
- force the immediate termination of an instance ;
- get usage statistics (users count, contributions count) for deployed instances (or these endpoints should be exposed by the instances, not this deployment API?);
The OpenAPI (Swagger) specification is an API description format which allows to describe an API in a non-ambiguous and very precise way.
You may use the Swagger editor to read the specification in a more graphical way:
You may generate implementations of both APIs clients in various languages by using the Swagger codegen tool.
Contributions to this document are welcome as pull-requests.
This code/content is published under the MIT License.