Skip to main content

RAPID and OData

RAPID Profile is a subset of the conventions defined in OData that can be applied to any RESTful API. A RAPID service can easily support generic OData V4 clients by:

RAPID services MAY support any additional conventions defined in the OData specification. RAPID services SHOULD

Support OData canonical key syntax

Services SHOULD support the OData parens key syntax as an alternate syntax.

GET http://rapid-pro.org/company/employees(2)

To be interoperable with OData clients, RAPID services that do not support the above OData key convention MUST include an @id property whose string value is a URL that can be used to retrieve the resource.

Support $ prefix for built-in query options

In addition to the "friendly" query option names filter, orderby, select, ... services SHOULD also support the $-prefixed versions $filter, $orderby, $select, ... with the same semantics.

Support qualified action and function names

In addititon to "short" action and function names services SHOULD also support namespace-qualified action and function names, for example

POST http://rapid-pro.org/company/employees/1/youreFired
POST http://rapid-pro.org/company/employees/1/enterprise.youreFired

where enterprise is the schema namespace that defines the youreFired action.

Support XML resource description

To support generic OData V4 clients, RAPID services SHOULD provide their resource description at /$metadata (also) in XML format according to OData V4 CSDL XML.

Following OData conventions for OData V4 Clients

A RAPID service determines that a request is from a generic OData V4 client by looking for any of the following:

  • An OData-MaxVersion header
  • An OData-Version header
  • An Accept or Content-Type header with a value of application/json suffixed with an OData-specific format parameter