RESTful principles

Rules

• The system is organized as resources with capabilites
• The system is connected through hyper-media
• Stateless Communication
• Uniform Interfaces

Resources and Representations

• Resources must have unique identities
• Resources expose sets of capabilities
• Resources can have multiple representations
• Resources must difine a caching policy
• Capabilities should be accessible through uniform interfaces

Hyper-media

• Links are the application entry points
• Links decouple communication
• Links are platform independant

Actions and Side effects

• Actions should be predictable
• Side effects should be made explict

HTTP Verbs

• GET: retrieve resources, should not change data
• POST: create resources
• PUT: change/update resources
• DELETE: remove resources
• HEAD: read resources headers

DOes:

• Use well known formats and protocols
• Do not keep session state on the server between requests
• Return links to further actions and resources
• Use templates and forms to help clients build complex requests

DONTs:

• Thinking only about pretty looking templated URLs
• Constructing URLs manually
• Hardcoding URLs

To-do representation example

  {
    "id": "id123",
    "message": "get milk",
    "done": false,
    "methods": {
      "get": {  "url": "todo.xyz/task/id123", "method": "GET" },
      "toggle": { "url": "todo.xyz/task/id123/toggle", "method": "PUT" },
      "edit": { "url": "todo.xyz/task/id123/message", "method": "PUT" },
      "delete": { "url": "todo.abc/task/id123", "method": "DELETE" }
    }
  }
  

    <article сlass="todo-task" id="id123">
      <form сlass="toggle"
        action="todo.xyz/task/id123/toggle" method="PUT">
        <input type="checkbox" checked/>
        <input type="submit" value="toggle"/>
      </form>
      <p class="message">get milk</p>
      <a href="todo.xyz/task/id123">View item</a>
      <form class="delete" action="todo.abc/task/id123"
        method="DELETE">
        <input type="submit" value="delete"/>
      </form>
    </article>
  

To-do representation example

Web Hooks

1. A client service sends our service a callback url
2. Our service stores the callback urls per event type
3. Our service sends data to all callback urls when a specific event happens within our sevice
4. The client service processes the event data

Links

• Original REST paper
• GOTO 2014 REST (youtube)
• Does and Donts

Course Schedule: