RCS v2 Service Contract

This release of RCS publishes endpoints at /v2. The endpoints at /v2 are compatible with registration requests for schema version 2.0 and document requests for RAMP version 2 (in support of Federal Geospatial Platform’s R2 Visualization requirements).

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 /v2/doc/[lang]/[key]

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 2.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
  • key not found: 404 Not Found, response body empty

GET /v2/docs/[lang]/[key]{,[key]}{/[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
  • key not found: 200 normal response, the corresponding fragment will be structured as: {"error_code":404,"key":"[key]"}

PUT /v2/register/[key]

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":"2.0","en":(payload),"fr":(payload) }

Payload Type basic

The basic payload describes elements common to all registered services, and is not a service type unto itself:

{
    "service_url": (str: URL to ESRI REST Feature Layer Endpoint),
    "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 is 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 feature

The feature payload should conform to:

{
    "service_url": (str: URL to ESRI REST Feature Layer Endpoint),
    "service_type": (str: Type of Esri Feature service),
    "service_name": (str: Layer Name),
    "display_field": (str: Default attribute for identifying features),
    "loading_mode": (str: Specifies the layer loading mode: either snapshot -
    load all data upfront, or ondemand load data as needed),
    "max_allowable_offset": (int: Simplification factor for the layer geometry;
    may be omitted in which case no value will be provided in the output
    leaving the viewer to apply its own logic.),
    "tolerance": (int: Tolerance, in pixels, of feature queries),
    "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, loading_mode, max_allowable_offset, tolerance 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

Payload Type imagery

The imagery service payload should conform to:

{
    "service_url": (str: URL to ESRI REST Feature Layer Endpoint),
    "service_type": (str: Type of Esri Imagery service, esriTile or esriImage),
    "service_name": (str: Layer Name),
    "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

Payload Type ogc wms

The wms payload should conform to:

{
    "service_url": (str: URL to WMS Service),
    "service_name": (str: Name of the service endpoint, used for display),
    "service_type": (str: Service type of the endpoint, ogcWms (support for ogcWmts may come at a later date)),
    "scrape_only": (str array: Indicates which layer entries should be scraped,
    all layers should be identified by their Name element.),
    "recursive": (bool: Indicates if children should be scraped and made available
    as individual layers to the viewer),
    "legend_format": (str: MIME type)",
    "feature_info_type": (str: MIME type, limited to "text/html;fgpv=summary", "text/html", "text/plain", "application/json"),
    "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
  • service_name, scrape_only, metadata are optional

Payload Type esri map

The esri map service (grouped layers) payload should conform to:

{
    "service_url": (str: URL to WMS Service),
    "service_name": (str: Name of the service endpoint, used for display),
    "service_type": (str: Service type of the endpoint, either esriMapServer
    or esriFeatureServer),
    "scrape_only": (int array: Indicates which layer entries should be scraped,
    all layers should be identified by their Name element.),
    "recursive": (bool: Indicates if children should be scraped and made available
    as individual layers to the viewer),
    "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
  • service_name, scrape_only, metadata, recursive, are optional

DELETE /v2/register/[key]

Success Code: 204

Request Body: Empty

Request Headers: Implement the Request Signing protocol

Response Body: Empty

Error Conditions:

  • key 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 /v2/upgrade/[key]

Success Code: 200

Request Body: Empty

Request Headers: Implement the Request Signing protocol

Request Params: key for an already registered v1 layer

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

Error conditions:

  • Record not found in database: Upgrade failed 404
  • Already upgraded

POST /v2/refresh/[params]

Success Code: 200

Request Body: JSON Object

Request Headers: Implement the Request Signing protocol

Request Params: Either ‘all’ or a positive integer indicating the minimum age in days of a record before it should be updated

Response Body: {"updated":["0"],"errors":{},"limit_reached":false}

POST /v2/update/[key]

Success Code: 200

Request Body: Empty

Request Headers: Implement the Request Signing protocol

Request Params: Only the fields that require updating on a pre-registered entry. “service_type” is a mandatory field, if trying to change this, please re-register entirely.

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

Error conditions:

  • key 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

RCS v1 Endpoints

v1 registration of services, as well as simplification and updatefeature endpoints have been deprecated in favour of v2.

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]/[key]

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
  • key not found: 404 Not Found, response body empty

GET /v1/docs/[lang]/[key]{,[key]}{/[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
  • key not found: 200 normal response, the corresponding fragment will be structured as: {"error_code":404,"key":"[key]"}

DELETE /v1/register/[key]

Success Code: 204

Request Body: Empty

Request Headers: Implement the Request Signing protocol

Response Body: Empty

Error Conditions:

  • key 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