Sample Project, RESTful API

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

NOTE: see section "Final touches" in the Sample Project, Setup document; if you don't make the changes described in that section, then your base URL will be http://localhost:8080/REST_lamp/

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}

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/lamps

Example Response

  [
    {
      "id": 1,
      "ison": false
    },
    {
      "id": 2,
      "ison": false
    }
  ]

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/lamps/1

Example Response

  {
    "id": 1,
    "ison": false
  }

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/lamps

Example Response

Header

  Location: http://localhost:8080/lamps/1

Body

  {
    "id": 1,
    "ison": false
  }

Turns the lamp identified by {id} on/off. NOTE: a PUT will replace the resource identified by {id}.

HTTP response code: 200 (OK).

Resource URL

/lamps/{id}

Parameters

None.

Example Request

  PUT http://localhost:8080/lamps/2

Here is the body of the PUT request.

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

The body of the response will be empty.