Internal Service Overview¶
Internal Services in 3DIAX are based around two technology pillars. First, all services internal to 3DIAX run inside docker containers. Second, all services internal to 3DIAX expose a RESTful HTTP interface
Docker containers are required to run in 3DIAX’s cloud. This allows software vendors to have complete control over the runtime environment in which their service operates. Documentation on Docker containers are available from various sources, though we recommend the Official Docker Tutorial for those who are new to Docker and containers. Docker containers at Authentise run inside a distributed Docker Swarm. In general you should assume that your container will be limited to 512M of RAM and a single CPU, though exceptions can be made on request. If you have questions or assistance with container technology feel free to contact Authentise at firstname.lastname@example.org
It is preferred, though not required, that your Docker image be available on the Docker Hub. The image can be private - you simply need to share read access to the image with
authentiseautomation. Your Docker image should be tagged uniquely - do not use the
latest tag. Image tags should use semantic versioning. If you are using a git repository for source code management please use a tag format such as
X is the major version number,
Y is the minor version number,
Z is the number of commits passed version
X.Y‘s tag, and
gNNNNNN is the short form hash of the commit. This is the same value you would see from the output of
git describe. This structure makes it very easy to relate particular container images to source code versions. If you do not use git feel free to specify another semantic version scheme that relates to your SCM tool of choice.
RESTful HTTP interface¶
Services running in Authentise’s cloud communicate with each other over HTTP. This is a protocol that has some major drawbacks, but overall provides an interface that is easy to implement in any language. HTTP services should be able to send and receive JSON. Operations using the
GET method should be idempotent. Requests should respond within 3 seconds to avoid timing out. Long-running operations should use an architecture where a client creates the operation using
POST and the response provides a URL where the client can request status updates. The client then makes a
GET request to that URL to get updated information on the long-running operation.
Services using an HTTP interface should expect to be load-balanced on a naive load balancer such that successive requests may be serviced by separate copies of the service that do not share memory directly. Data sharing should be achieved through client cookies and some kind of coordinated data store such as a shared in-memory cache or database.
Authentise has several backend services that providers can use for common tasks such as making callback requests, handling user sessions, and granting permissions to resources. If you are interested in making use of these services please contact contact us
When providing an External Service the provider validate and provide JWTs as described in the External Service Provider Reference. This is not true of internal services. Because the services run inside Authentise cloud there is no need to validate the identity and authenticity of the service. Authentise instead can use the fact that the service is running in our datacenter to authenticate its actions.
When providing an Internal Service to Authentise you must include documentation on the various endpoints for the service. The documentation should include every URL path the service supports, the HTTP methods that can be used on the path (
POST, etc), the HTTP status codes that can be returned during normal operation, and the JSON data that the endpoint accepts on
PATCH and emits on
DELETE, if any. A good example template is the Reference or the Reference.