RESTful API

RESTful APIs explicitly take advantage of HTTP methodologies defined by the RFC 2616 protocol. They simply use "PUT" to change the state of or update a resource, which can be an object, file or block; "GET" to retrieve a resource; POST" to create that resource; and "DELETE" to remove it.

https://github.com/RestCheatSheet/api-cheat-sheet

RAML

An RAML example that demonstrate how to think about RESTful API

http://raml.org/developers/raml-200-tutorial

• USE CASE
  Build a music Jukebox. While the physical device will be responsible for displaying the information and capturing the user input, it will be relying on your API to retrieve the information requested. The Jukebox needs to be able to:

  • Show the full list of artists.
  • Show the full list of albums.
  • Show the list of artists by nationality.
  • Show the list of albums by genre.
  • Search for a song by title.
  • Show a particular artist's albums collection.
  • Show a particular album's songs list.
  • Play a song (by specifying the song id).
  • Enter new Artists, Albums and Songs (only authenticated users).

• Basic structure

/songs
  get
  post
  /{songId}
    get
    /file-content
      get
      post
/artists
  get
  post
    /{artistId}
      get
      /albums
        get
/albums
  get
  post
    /{albumId}
      get
      /songs
        get

• Specify HTTP body parameter
  • form parameter
  • schema

RESTful API design and tools

http://blog.luisrei.com/articles/rest.html

Resources are mapped to URLs, actions are mapped to verbs and the rest goes in the headers.

• Use RAML

• Swagger

• API blueprint

• Tool for modeling web api
  http://modeling-languages.com/modeling-web-api-comparing/

API Design and Implementation Consideration

** For each of the following item, consider how to implement:**

For Flask

• Request processing

  • url (@route)

  • http method

  • header (how to parse header)

  • body parameter (how to parse these parameter)

    • regular dictionary style parameter
    • file object ...

  • query parameter

• Generate response