Cúram REST API methods

Cúram REST APIs support GET, POST, PUT, and DELETE methods on resources. The GET method is used to read data from Cúram. The POST method is used to create a resource. The PUT method is used to modify a resource, and the DELETE method is used to delete a resource.

Refer to the following example to see how methods operate on a REST resource that allows for the creation, modification, and deletion of notes.

In the example, the note resource is represented by /notes. There are two resource paths required:

The collection resource, used to retrieve all notes and create new notes, /notes
The member resource, used to operating on a single, specific note, /notes/{note_id}

Each of these resources supports a number of methods and the following table defines how you might use the methods for the two notes resource paths:

Table 1.
Method	Resource	Notes	Successful HTTP Response Code
GET	/notes/	Gets all notes in the system.	200
POST	/notes/	Creates a new note.	201
PUT	/notes/{note_id}	Deletes an existing note.	200
GET	/notes/{note_id}	Returns a specific note.	200
DELETE	/notes/{note_id}	Deletes a specific note.	204

A note resource returns a JSON representation of a note. For example:

{
  "note_id": "1234"
  "text": "A new note!!"
}

GET Collection Resource

The GET /notes method will return a list of notes, which is represented as an array of notes, where the array is identified by the data property in the JSON representation:

{ data : [{
  "note_id": "1234"
  "text": "A new note!!"
},
{
  "note_id": "1235"
  "text": "Another note!!"
}
]}

POST Collection Resource

You use the POST /notes method to create a new note. A POST request is made to this resource, with a request body containing representation of the new Note, as follows:

{
  "text": "A new note!!"
}

No note_id property is passed as part of the representation, as Cúram automatically generates the unique identifier for the note.

The result of this request is a HTTP 201 Created response status code. The response body is empty. The response header contains a location entry that details the URL for the newly requested resource, for example "location": https://host:port/Rest/v1/notes/1234.

GET Member Resource

If 1234 is the unique identifier for the newly created resource in the example, you can make a GET request using the /notes/{note_id} member resource URL to retrieve the representation of the Note. For example, https://host:port/Rest/v1/notes/1234. This returns the JSON representation of a single note in the response body.

PUT Member Resource

To modify a Note, use the PUT /notes/{node_id} method. A PUT request is made to this resource (for example, /notes/1234), with a request body containing the representation of the Note to be modified:

{
  "note_id": "1234"
  "text": "Updated text"
}

Both the note_id and text properties are included in the request body, and the note_id must match the value in the resource URL, that is, 1234 in this example. The result of this request is an HTTP 200 OK response status code and the response body contains a representation of the resource.

The response body returns the modified resource to allow for properties that were modified by Cúram to be updated, for example a version number property that is used for optimistic locking.

DELETE Member Resource

To delete a note, the DELETE /notes/{note_id} method should be used. A DELETE request is made to this resource, with an empty request body. For example, /notes/1234.The result of this request is an HTTP 204 No Content response status code.