CloudServices/Sagrada/ServiceDiscovery

Summary

The Services Discovery API is the single entrypoint into a Sagrada instance. It defines what services are offered, what versions of those services are understood, and the URLs needed to continue interacting with Sagrada. It also contains URLs to metainformation about the Sagrada instance, such as the privacy policy. Clients need to be configured with this entrypoint, and should be able to do all further work from there.

The results returned by the API consist of a JSON blob encapsulating all this data. As it is not expected to grow particularly large, and can be cached by the client for fairly lengthy periods of time, there is no need to break it down into multiple connected files.

Resource URLs defined in the Services Discovery response should be complete - the client never needs to do anything to the URL to access the resource.

This API is unauthenticated and publicly available from a single location, as it will be requested in the request chain before any authorization step.

API

GET /discover

This is a straightforward GET call, returning a JSON object containing all relevant data.

GET https://directory.services.mozilla.com/discover

HTTP Response Codes

200	Success
404	Resource not found (clients should treat this as a configuration error)
503	Service Unavailable, clients should respect Retry-After if provided, otherwise should retry no more than once per 15 minutes.

Response Object Format

There are two top-level objects, services and urls. services contains the full set of available services, with per-API-version authentication endpoints. urls is for non-service URLs, such as ToS/PP links, and any other non-service URLs that may be necessary/needed for clients.

{
   "services": {
       "simple_storage": {
           "2.0": "https://token.services.mozilla.com/simple_storage/2.0",
           "2.1": "https://token.services.mozilla.com/simple_storage/2.1"
       },
       "durable_storage": {
           "1.0": "https://token.services.mozilla.com/durable_storage/1.0"
       }
   },
   "urls": {
       "privacy_policy": "https://services.mozilla.com/pp/",
       "terms_of_service": "https://services.mozilla.com/tos/"
   }
}

Implementation Plan

Requirements

• Uptime: >= Token Server uptime
• Geo-DNS: Yes
• Separate hostname from token server, for future flexibility.

Initial Launch

As this is a flat file, there's no need at this point for special infrastructure. Initially this file can be managed by the ops puppet instance and served from the token servers, and directory.services.mozilla.com can be a cname to token servers's gslb-enabled dns name.

Longer Term

As this is largely driven by the services configured/supported by the Token Server for the instance, we will almost certainly want to auto-generate the flat file based on a common data source. This is an operational optimization, and not a requirement in Q2 and likely even through 2012. Since we're already routing these requests to the token server with a static file request, it will be easy to push forward and deploy an application that serves the mapping, instead.