Skip to content

Latest commit

 

History

History
101 lines (73 loc) · 2.24 KB

RESTful-API.md

File metadata and controls

101 lines (73 loc) · 2.24 KB

RESTful API

What is REST?

REST: Representational state transfer.

Six guiding constraints define a RESTful system:

  • Client-server Architecture
  • Statelessness
  • Cacheability
  • Layered System
  • Code on demand (optional)
  • Uniform interface
    • Resource identification in requests
    • Resource manipulation through representations
    • Self-descriptive messages
    • Hypermedia as the engine of application state (HATEOAS)

reference

There is no REST API

image from http://slides.com/eungjun/rest

REST doesn’t describe APIs. REST describes the architectural characteristics of an entire system, which includes all of the different components of that system.

from: https://www.howarddierking.com/2016/09/15/there-is-no-rest-api/


PUT vs. PATCH (in HTTP API)

TL;DR

PUT is used to replace the entire entity. PATCH is used to patch the entity.


When using PUT, it is assumed that you are sending the complete entity, and that complete entity replaces any existing entity at that URI.

{ "username": "skwee357", "email": "[email protected]" }

If you POST this document to /users, as you suggest, then you might get back an entity such as

## /users/1
{
    "username": "skwee357",
    "email": "[email protected]"
}

If you want to modify this entity later, you choose between PUT and PATCH. A PUT might look like this:

PUT /users/1
{
    "username": "skwee357",
    "email": "[email protected]"       // new email address
}

You can accomplish the same using PATCH. That might look like this:

PATCH /users/1
{
    "email": "[email protected]"       // new email address
}

Using PUT wrong

GET /users/1
{
    "username": "skwee357",
    "email": "[email protected]"
}
PUT /users/1
{
    "email": "[email protected]"       // new email address
}

GET /users/1
{
    "email": "[email protected]"      // new email address... and nothing else!
}

reference: https://stackoverflow.com/a/34400076