RestProposal

Proposal for the Dime REST API

We will provide a JSON REST API. JSON REST APIs are cool. This is a first guess, what endpoints might be useful for managing the Dime Entities:

• Activity
• Customer
• Project
• Service
• User

Manage Services

Services should be managed via the /services endpoint:

/services

You can retrieve a list of all services:

Request:

GET /services HTTP/1.0

Response:

HTTP/1.1 200 OK
Content-Type: application/json

[
 { 
   "id": "13",
   "name": "Coding",
   "description": "Producting code."
 },
 { 
   "id": "14",
   "name": "Fixing",
   "description": "Fixing code."
 },
]

You can retrieve one single service:

Example

Request:

GET /services/42 HTTP/1.0

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{ 
  "id": "42", 
  "name": "Documentation", 
  "description": "Creating a decent documentation." 
}

You can create a new service. If a value for id is supplied, it SHOULD be ignored. The API will respond with a service object that has the created id.

Example

Request:

POST /services HTTP/1.0

{ 
  "name": "Documentation", 
  "description": "Creating a decent documentation." 
}

Response:

HTTP/1.1 201 Created

{
  "id": "42",
  "name": "Documentation",
  "description": "Creating a decent documentation."
}

You can retrieve a single service object. You MUST supply an existing id.

Request:

GET /services/42 HTTP/1.0

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{ 
  "id": "42",
  "name": "Documentation",
  "description": "Creating a decent documentation."
}

You can update an existing service. You MUST supply a valid id.

Request:

PUT /somedatabase/some_doc_id HTTP/1.0
Content-Type: application/json
{
  "id": "42",
  "name": "Pimped docs",
  "description": "Made the documentation 23% more awesome."
}

Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": "42",
  "name": "Pimped docs",
  "description": "Made the documentation 23% more awesome."
}

Or just delete a service. The response object might be empty, and the HTTP status MUST be 200 if the object has been deleted, or does not exist.

Request:

GET /services/42 HTTP/1.0

Response:

HTTP/1.1 200 OK
Content-Type: application/json

Mind: http://stackoverflow.com/questions/1619152/how-to-create-rest-urls-without-verbs/1619677#1619677