REST API design

POST /resources HTTP/1.1

{
  "some": "some data",
  "other": "some other data"
}

GET /resources/ID

PATCH /resources HTTP/1.1

{
  "other": "modified data"
}

PUT /resources/ID HTTP/1.1

{
  "some": "some new data",
  "other": "some other new data"
}

DELETE /resources/ID

GET /resources 
POST /resources
PATCH /resources
PUT /resources 
DELETE /resources

POST /resources 
[
  {
    "id": "CREATION1",
    "body": {"resource's": "data"}
  },
  {
    "id": "CREATION2",
    "body": {"resource's": "data"}
  }
]



POST /resources 
{
  "CREATION1" : {"resource's": "data"},
  "CREATION2" : {"resource's": "data"}
}

PATCH /resources
{
  "ID1" : {"resource's": "data"},
  "ID2" : {"resource's": "data"}
}

GET /resources?ids=ID1,ID2

DELETE /resources?ids=ID1,ID2

[
  {
    "id": "ID1",
    "status": "201",
    "headers": [
      {"header's name": "header's value"}
    ],
    "body": { "the": "response's body"}
  },
  {
    "id": "ID2",
    "status": "400",
    "headers": [
      {"header's name": "header's value"}
    ],
    "body": { "the": "response's body"}
  }
]




{
  "ID1": {
    "status": "201",
    "headers": [
      {"header's name": "header's value"}
    ],
    "body": { "the": "response's body"}
  },
  "ID2": {
    "status": "400",
    "headers": [
      {"header's name": "header's value"}
    ],
    "body": { "the": "response's body"}
  }
}

{
  "CREATION1" : {"resource's": "data"}
}

{"resource's": "data"}

//and

{
  "CREATION1" : {"resource's": "data"}
  "CREATION2" : {"resource's": "data"}
}

POST /resources
or
POST /resource-modifications

[
  {
    "id": "ID1",
    "method": "DELETE"
  },
  {
    "id": "ID2",
    "method": "PATCH",
    "body": {"resource's": "data"}
  }
]

POST /bulk
or
POST /batch

[
  {
    "id": "ACTION1",
    "uri": "/resources/ID1",
    "method": "DELETE"
  },
  {
    "id": "ACTION2",
    "uri": "/another-resources/ID2",
    "method": "PATCH",
    "body": {"resource's": "data"}
  }
  ,
  {
    "id": "ACTION3",
    "uri": "/resources",
    "method": "POST",
    "body": {"resource's": "data"}
  }
]

GET /tickets - Retrieves a list of tickets
GET /tickets/12 - Retrieves a specific ticket
POST /tickets - Creates a new ticket
PUT /tickets/12 - Updates ticket #12
PATCH /tickets/12 - Partially updates ticket #12
DELETE /tickets/12 - Deletes ticket #12


//relations:
GET /tickets/12/messages - Retrieves list of messages for ticket #12
GET /tickets/12/messages/5 - Retrieves message #5 for ticket #12
POST /tickets/12/messages - Creates a new message in ticket #12
PUT /tickets/12/messages/5 - Updates message #5 for ticket #12
PATCH /tickets/12/messages/5 - Partially updates message #5 for ticket #12
DELETE /tickets/12/messages/5 - Deletes message #5 for ticket #12

//filtering
GET /tickets?state=open

//sorting
GET /tickets?sort=-priority 
GET /tickets?sort=-priority,created_at 
//searching
--Retrieve recently updated tickets
GET /tickets?sort=-updated_at 
--Retrieve recently closed tickets
GET /tickets?state=closed&sort=-updated_at 
--Retrieve the highest priority open tickets mentioning the word 'return'
GET /tickets?q=return&state=open&sort=-priority,created_at 

//Aliases for common queries
GET /tickets/recently_closed

GET /tickets?fields=id,subject,customer_name,updated_at&state=open&sort=-updated_at

//AVOID
{
  "data" : {
    "id" : 123,
    "name" : "John"
  }
}

//PREFER
 {
    "id" : 123,
    "name" : "John"
  }

//The number of allowed requests in the current period
X-Rate-Limit-Limit

//The number of remaining requests in the current period
X-Rate-Limit-Remaining

//The number of seconds left in the current period
X-Rate-Limit-Reset

GET /tickets/12?embed=customer.name,assigned_user
{
  "id" : 12,
  "subject" : "I have a question!",
  "summary" : "Hi, ....",
  "customer" : {
    "name" : "Bob"
  },
  assigned_user: {
   "id" : 42,
   "name" : "Jim",
  }
}

If-None-Match

Last-Modified 
Modified-Since

//AVOID
{
  "code" : 1234,
  "message" : "Something bad happened :(",
  "description" : "More details about the error here"
}


//PREFER
{
  "code" : 1024,
  "message" : "Validation Failed",
  "errors" : [
    {
      "code" : 5432,
      "field" : "first_name",
      "message" : "First name cannot have fancy characters"
    },
    {
       "code" : 5622,
       "field" : "password",
       "message" : "Password cannot be blank"
    }
  ]
}

//Response to a successful GET, PUT, PATCH or DELETE. Can also be used for a POST that doesn't result in a creation.
200 OK

//Response to a POST that results in a creation. Should be combined with a Location header pointing to the location of the new resource
201 Created

//Response to a successful request that won't be returning a body (like a DELETE request)
204 No Content

//Used when HTTP caching headers are in play
304 Not Modified

//The request is malformed, such as if the body does not parse
400 Bad Request

//When no or invalid authentication details are provided. Also useful to trigger an auth popup if the API is used from a browser
401 Unauthorized

//When authentication succeeded but authenticated user doesn't have access to the resource
403 Forbidden

//When a non-existent resource is requested
404 Not Found

//When an HTTP method is being requested that isn't allowed for the authenticated user
405 Method Not Allowed

//Indicates that the resource at this end point is no longer available. Useful as a blanket response for old API versions
410 Gone

//If incorrect content type was provided as part of the request
415 Unsupported Media Type

//Used for validation errors
422 Unprocessable Entity

429 Too Many Requests

PATCH /my/data HTTP/1.1
   Host: example.org
   Content-Length: 326
   Content-Type: application/json-patch+json
   If-Match: "abc123"

   [
     { "op": "test", "path": "/a/b/c", "value": "foo" },
     { "op": "remove", "path": "/a/b/c" },
     { "op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ] },
     { "op": "replace", "path": "/a/b/c", "value": 42 },
     { "op": "move", "from": "/a/b/c", "path": "/a/b/d" },
     { "op": "copy", "from": "/a/b/d", "path": "/a/b/e" }
   ]