RCS Service Contract

This release of RCS publishes endpoints at /v1 and /v0.9. The endpoints at /v1 are compatible with registration requests for schemas 1.0 and 1.1 and document requests for RAMP schema 1.0 .

The current JSON schema is used to validate registration requests is at:

An older schema for RAMP versions prior to schema 1.0 is documented at:

GET /v1/doc/[lang]/[smallkey]

Success Code: 200

Request Body: Empty

Response Body: JSON Object

The response will have a JSON configuration fragment to be merged into the RAMP configuration. It will be compatible with RAMP schema 1.0, although as it is a fragment it will not validate against the schema without additional configuration being supplied.

Error conditions:

  • invalid language code: 400 Bad Request, response body empty
  • smallkey not found: 404 Not Found, response body empty

GET /v1/docs/[lang]/[smallkey]{,[smallkey]}{/[sortarg]}

Success Code: 200

Request Body: Empty

Response Body: JSON Array

The response will be an array of JSON objects, each object will be a JSON configuration fragment to be merged into the RAMP config. It will be compatible with RAMP schema 1.0, although as it is a fragment it will not validate against the schema without additional configuration being supplied.

Error conditions:

  • invalid language code: 400 Bad Request, response body empty
  • smallkey not found: 200 normal response, the corresponding fragment will be structured as: {"error_code":404,"smallkey":"[smallkey]"}

PUT /v1/register/[smallkey]

Success Code: 201

Request Body: JSON Object

Request Headers: Implement the Request Signing protocol

Response Body: Empty

Error Conditions:

  • payload does not conform to schema: 400 Bad Request, body contains {"errors":["message 1","message 2"]}
  • invalid timestamp format: 400 Bad Request
  • unable to verify metadata surce: 400 Bad Request
  • missing headers / unretrivable key: 401 Not Authorized
  • exception in processing: 500 Internal Server Error, empty body

Registration requests are validated against The body of the request should conform to:

{"version":"1.1.0","payload_type":("feature","wms"),"en":(payload),"fr":(payload) }
  • RCS currently accepts 1.0.0 and 1.1.0 requests

Payload Type feature

The feature payload should conform to:

{
    "service_url": (str: URL to ESRI REST Feature Layer Endpoint),
    "service_name": (str: Layer Name),
    "display_field": (str: Layer Attribute),
    "metadata": {
        "uuid": (str: a unique identifier),
        "catalogue_url": (str: URL describing the layer in full detail)
        "metadata_url": (str: direct URL to metadata for that layer)
    }
}
  • the service URL should not have any query string component
  • metadata, display_field, service_name are optional
  • where service_url specifies Feature Layer endpoint, this may be an endpoint from a Feature Service or a Map Service; what is important is that the URL should reference the layer id within it
  • NOTE metadata should be present for most layers, it is left as optional only for exceptional cases
  • one of uuid or *_url should be specified
  • metadata_url should be direct URL to the layer’s metadata which should be in XML format
  • catalogue_url should be a URL linking back to the catalogue’s page describing the layer
  • uuid should be a unique identifier which can be prefixed with a preconfigured metadata URL to retrieve specific metadata for that layer

Payload Type wms

The wms payload should conform to:

{
    "service_url": (str: URL to WMS Service),
    "layer": (str: Layer Identifier),
    "legend_format": (str: MIME type)",
    "feature_info_type": (str: MIME type),
    "metadata": {
        "uuid": (str: a unique identifier),
        "catalogue_url": (str: URL describing the layer in full detail)
        "metadata_url": (str: direct URL to metadata for that layer)
    }
}
  • the service URL should not have any query string component
  • layer is required and must match the a layer identifier specified in the WMS
  • legend_format is an optional string, if present it indicates legend support on the WMS and specifies the image MIME type to request from the server
  • feature_info_type is an optional field, if present it indicates feature info support on the WMS, default parsers are available for text/html (direct HTML code which can be inserted into a RAMP panel), text/plain (plain text which will be wrapped in a paragraph tag and then inserted into a RAMP panel NOTE: all formatting will be lost), and application/json (a JSON fragment which will have its top level properties displayed in a tabular format in a RAMP panel)
  • NOTE metadata should be present for most layers, it is left as optional only for exceptional cases
  • one of uuid or *_url should be specified
  • metadata_url should be direct URL to the layer’s metadata which should be in XML format
  • catalogue_url should be a URL linking back to the catalogue’s page describing the layer
  • uuid should be a unique identifier which can be prefixed with a preconfigured metadata URL to retrieve specific metadata for that layer

DELETE /v1/register/[smallkey]

Success Code: 204

Request Body: Empty

Request Headers: Implement the Request Signing protocol

Response Body: Empty

Error Conditions:

  • smallkey not found: 404 Not Found
  • invalid timestamp format: 400 Bad Request
  • missing headers / unretrivable key: 401 Not Authorized
  • exception in processing: 500 Internal Server Error, empty body

POST /v1/update/[age]

added in RCS 1.8.0

Success Code: 200

Request Body: Empty

Request Headers: Implement the Request Signing protocol

Request Params: age should be either “all” or a positive integer indicating the minimum age in days that a record should be before it is updated

Response Body: { "success": ["smallkey", …], "errors": {"smallkey": "message", …} }

Error conditions:

  • Age is invalid, error code 400, body {“error”:”argument should be either ‘all’ or a positive integer”}

PUT /v1/simplification/[smallkey]

added in RCS 1.9.0 DEPRECATED use /v1/updatefeature/[smallkey] instead

Success Code: 200

Request Body: JSON Object

Request Headers: Implement the Request Signing protocol

The body of the request should conform to:

{"user":"<user name>","factor":<simplification factor> }

Response Body: { "success": ["smallkey", …], "errors": {"smallkey": "message", …} }

Error conditions:

  • smallkey not found: 404 Not Found
  • smallkey maps to non-feature layer: 400 Record is not a feature layer
  • factor is not an integer: 400 Invalid payload JSON
  • exception in processing: 500 Internal Server Error, empty body

PUT /v1/updatefeature/[smallkey]

added in RCS 1.10.0

Success Code: 200

Request Body: JSON Object

Request Headers: Implement the Request Signing protocol

The body of the request should conform to one of:

{"en":(obj: config fragment), "fr":(obj: config fragment)}
{config fragment}

Either a common configuration fragment to be applied to both the English and French configuration or separate sections which are updated separately. The final configuration must be valid against the current configuration schema.

Response Body: smallkey

Error conditions:

  • smallkey not found: 404 {“errors”:[]}
  • unparseable JSON: 400 {“errors”:[]}
  • smallkey maps to non-feature layer: 400 {“errors”:[]}
  • error in request validation: 400 {“errors”:[]}
  • exception in processing: 500 Internal Server Error, empty body