Sample Project, RESTful API

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

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 PUT to create a new lamp and POST to turn a lamp on/off.

Here is the full API:

• GET /lamps
• GET /lamps/{id}
• PUT /lamps
• POST /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

	
  PUT 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.

HTTP response code: 200 (OK).

Resource URL

/lamps/{id}

Parameters

None.

Example Request

	
  POST http://localhost:8080/lamps/2

Here is the body of the POST request.

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

The body of the response will be empty.