Skip to main content

Modifying Resources

RAPID defines simple REST operations for Create, Update, and Delete.

Creating a Resource​

Resources are added to a collection by submitting a POST request to the collection.

TemplatePOST {collection-resource-path}
ExamplePOST http://rapid-pro.org/company/employees

Body:

{
  "firstName": "Elroy",
  "lastName": "Jetson",
  "title": "Intern"
}

Payloads sent to the service don't require the @context property because the request defines the expected shape of the payload. If specified, the @context is ignored by the service.

Properties that are nullable or have a default value may be omitted from the POST request.

The service returns, at minimum, a Location header specifying the URL for the created resource. It may also include a payload containing the values of the newly created resource, including default or computed values.

Deep Insert​

When creating a new resource, related resources can be created and associated in the same request.

TemplatePOST {collection-resource-path}
ExamplePOST http://rapid-pro.org/competitors

Body:

{
  "name": "Cogswell's Cosmic COGs",
  "incoporated": "2054-10-4",
  "stockSymbol": "cgswl",
  "employees": [
    {
      "firstName": "Spencer",
      "lastName": "Cogswell",
      "title": "CEO"
    }
  ]
}

Updating a Resource​

Resources are updated by submitting a PATCH request to the URL identifying the resource.

TemplatePATCH {single-resource-path}
ExamplePATCH http://rapid-pro.org/company/employees/5

Body:

{
  "title": "Manager"
}

The payload for a PATCH request need only include the properties that are being updated. Properties not specified in the payload are not changed.

Upserting a Resource​

Where the key value is specified by the client, not generated by the server, a resource can be created by submitting a PATCH request to the URL that will identify the resource.

TemplatePATCH {single-resource-path}
ExamplePATCH http://rapid-pro.org/company/employees/5

Body:

{
  "firstName": "Elroy",
  "lastName": "Jetson",
  "title": "Intern"
}

If the resource with the specified URL already exists, it is updated, otherwise a new resource is created.

Deleting a Resource​

Resources are deleted by submitting a DELETE request to the URL identifying the resource.

TemplateDELETE {single-resource-path}
ExampleDELETE http://rapid-pro.org/company/employees/2