Sample Project, RESTful API

For purposes of this API description, all URLs are relative to the base url of http://localhost:8080/rest-lamp/api/demo/.

Also, all data is in JSON format. A GET request will return JSON. A PUT or POST will submit a JSON document.

To keep things simple, no authentication is required to access any resource.

The requirements are very simple and they translate to a very simple API.

GET will be used to get the array of existing lamps or the detail for a specific lamp.

We'll use POST to create a new lamp and PUT to turn a lamp on/off (update a lamp).

Here is the full API:

• GET /lamps
• GET /lamps/{id}
• POST /lamps
• PUT /lamps/{id}
• DELETE /lamps/{id}

Returns an array of all lamps that have been created.

HTTP response code: 200 (OK).

Resource URL

/lamps

Parameters

None.

Example Request

  GET http://localhost:8080/rest-lamp/api/demo/lamps

Example Response

  [
    {
      "id": "a40a1736-8586-45e5-b141-fd77f8ffeda3",
      "ison": false
    },
    {
      "id": "9c65fa61-6964-437f-9c07-fd8515e6b285",
      "ison": true
    }
  ]

Returns the lamp described by {id}.

HTTP response code: 200 (OK), or 404 (Not Found).

Resource URL

/lamps/{id}

Parameters

None.

Example Request

  GET http://localhost:8080/rest-lamp/api/demo/lamps/9c65fa61-6964-437f-9c07-fd8515e6b285

Example Response

  {
    "id": "9c65fa61-6964-437f-9c07-fd8515e6b285",
    "ison": true
  }

Creates a new lamp.

HTTP response code: 201 (Created). The header of the reponse contains URI for the newly created lamp.

Resource URL

/lamps

Parameters

None.

Example Request

  POST http://localhost:8080/rest-lamp/api/demo/lamps

with the following body:

  {
    "id": "",
    "ison": true
  }

NOTE: the POST method will create the resource and assign it an id, whatever value is specified in the body of the POST will be ignored.

Example Response

Header

  Location: http://localhost:8080/rest-lamp/api/demo/lamps/a40a1736-8586-45e5-b141-fd77f8ffeda3

Body

  {
    "id": "a40a1736-8586-45e5-b141-fd77f8ffeda3"
    "ison": false
  }

The body of the response is technically not necessary because the URI of the newly created resource is available in the 'Location' header; it is included in this sample API as an example of how you can do it if you want to.

A PUT method will replace the lamp at /lamps/{id} with the lamp described in the body of the PUT request. It can thus be used to turn the lamp identified by {id} on/off.

HTTP response code: 204 (No Content).

Resource URL

/lamps/{id}

Parameters

None.

Example Request

  PUT http://localhost:8080/rest-lamp/api/demo/lamps/a40a1736-8586-45e5-b141-fd77f8ffeda3

Here is the body of the PUT request.

  {
    "id": "a40a1736-8586-45e5-b141-fd77f8ffeda3",
    "ison": true
  }

The body of the response will be empty.

Removes the lamp identified by {id}.

HTTP response code:

• 204 (No content) if the entity has been removed and there is no additional information in the body of the response.
• 404 (Not found) if the lamp identified by {id} doesn't exist.

Resource URL

/lamps/{id}

Parameters

None.

Example Request

  DELETE http://localhost:8080/rest-lamp/api/demo/lamps/9c65fa61-6964-437f-9c07-fd8515e6b285

Example Response

The body of the response is empty.