REST API DESIGN PRACTICE

OOCL

Blog API

• version 0 - Naive CRUD API for blog posts.
• version 1 - blog api made RESTful
• version 2 - add support for tags
• version 3 - add support for comments
• version 4 - add support for authors
• version 5 - authentication

A API Design Case:
https://www.ibm.com/developerworks/cn/webservices/0907_rest_soap/

https://www.upwork.com/hiring/development/soap-vs-rest-comparing-two-apis/
Resourced base vs ehavior base like OOP vs OPP

Blog API - v0

This API is designed to show how not to design a REST API.

End Points

List Posts

GET /lists-posts
---
200 OK
{
    "posts": [{
        "id": 1,
        "title": "Hello World",
        "body": "My first blog post"
    }]
}

Create Post

POST /create-post

{
    "post": {
        "title": "Hello World",
        "body": "My first blog post"
    }
}
---
200 OK

{"status": "created", "id": 1}

Show Post

GET /show-post?id=1

{
    "post": {
        "title": "Hello World",
        "body": "My first blog post"
    }
}

Update Post

POST /update-post?id=1

{
    "post": {
        "title": "Hello World",
        "body": "My first blog post"
    }
}
---
200 OK

{"status": "updated"}

Delete Post

GET /delete-post?id=1
---
200 OK

{"status": "deleted"}

Blog API - v1

Simple RESTful API for managing blog posts.

Topics

The blog API v1 deals with the following resources.

• post

End Points

List Posts

GET /posts
---
200 OK
Content-Type: application/json

[{
    "id": 1,
    "title": "Hello World",
    "body": "My first blog post"
}]

Create Post

POST /posts

{
    "title": "Hello World",
    "body": "My first blog post"    
}
---
200 OK
Content-Type: application/json

{
    "id": 1,
    "title": "Hello World",
    "body": "My first blog post"
}

Get Post

GET /posts/1
---
200 OK
Content-Type: application/json

{
    "id": 1,
    "title": "Hello World",
    "body": "My first blog post"
}

Update Post

PUT /posts/1
{
    "id": 1,
    "title": "Hello World",
    "body": "My first blog post with some edits"
}

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

{
    "id": 1,
    "title": "Hello World",
    "body": "My first blog post with some edits"
}

Delete Post

DELETE /posts/1
---
200 OK
Content-Type: application/json

{}

Blog API - v2

Simple RESTful API for managing blog posts.

Includes posts and tags.

Topics

The blog API v3 deals with the following resources.

• post
• tags

API - Posts

List Posts

GET /posts
---
200 OK
Content-Type: application/json

[{
    "id": 1,
    "title": "Hello World",
    "body": "My first blog post",
    "tags": ["hello"]
}]

Create Post

POST /posts

{
    "title": "Hello World",
    "body": "My first blog post",
    "tags": ["hello"]
}
---
200 OK
Content-Type: application/json

{
    "id": 1,
    "title": "Hello World",
    "body": "My first blog post",
    "tags": ["hello"]       
}

Get Post

GET /posts/1
---
200 OK
Content-Type: application/json

{
    "id": 1,
    "title": "Hello World",
    "body": "My first blog post",
    "tags": ["hello"]       
}

Update Post

PUT /posts/1
{
    "id": 1,
    "title": "Hello World",
    "body": "My first blog post with some edits",
    "tags": ["hello"]       
}

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

{
    "id": 1,
    "title": "Hello World",
    "body": "My first blog post with some edits",
    "tags": ["hello"]       
}

Delete Post

DELETE /posts/1
---
200 OK
Content-Type: application/json

{}

API - Tags

Lists Tags

GET /tags
---
200 OK

[{
    "name": "hello",
    "posts": [
        1
    ]
}]

Get a tag

GET /tags/hello
---
200 OK

{
    "name": "hello",
    "posts": [
        1
    ]
}

Questions?

• How to get a tag and all its posts for rendering a tag page?

  /tag/tagname/posts
  /tag/tagname (always include posts in the tag representation)
  /tag/tagname?expand=true

• How to find all the posts that are tagged with both tag A and tag B?

  /posts?tag=A&tag=B

• How to add a new tag to an existing post?

  PATCH /posts/1

  {
  "add": {
  "tag": "new-tag"
  },
  "delete": {
  "tag": "old-tag"
  }
  }
  See JSONPatch for more ideas.

How about exposing the tag as a subresource?

PUT /posts/1/tags/new-tag

• How to delete a tag from an existing post?

  DELETE /posts/1/tags/old-tag

Blog API - v3

Simple RESTful API for managing blog posts.

Includes posts, tags and comments.

Topics

The blog API v3 deals with the following resources.

• post
• tags
• comments

API - Posts

List Posts

GET /posts
---
200 OK
Content-Type: application/json

[{
    "id": 1,
    "title": "Hello World",
    "body": "My first blog post",
    "tags": ["hello"],
    "comments": [{
        "id": 12,       
        "author": "bahubali",
        "comment": "mahishmathi",
        "timestamp": "2017-05-12 10:15:00"
    }]
}]

Create Post

POST /posts

{
    "title": "Hello World",
    "body": "My first blog post",
    "tags": ["hello"]
}
---
200 OK
Content-Type: application/json

{
    "id": 1,
    "title": "Hello World",
    "body": "My first blog post",
    "tags": ["hello"],
    "comments": []      
}

Get Post

GET /posts/1
---
200 OK
Content-Type: application/json

{
    "id": 1,
    "title": "Hello World",
    "body": "My first blog post",
    "tags": ["hello"],
    "comments": [{
        "id": "12"
        "author": "bahubali",
        "comment": "mahishmathi",
        "timestamp": "2017-05-12 10:15:00"
    }]              
}

Update Post

PUT /posts/1
{
    "id": 1,
    "title": "Hello World",
    "body": "My first blog post with some edits",
    "tags": ["hello"]       
}

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

{
    "id": 1,
    "title": "Hello World",
    "body": "My first blog post with some edits",
    "tags": ["hello"],
    "comments": [{
        "id": 12,       
        "author": "bahubali",
        "comment": "mahishmathi",
        "timestamp": "2017-05-12 10:15:00"
    }]      
}

Delete Post

DELETE /posts/1
---
200 OK
Content-Type: application/json

{}

API - Comments

Get Comments of a post

GET /posts/1/comments
---
200 OK
[{
    "id": 12,
    "author": "bahubali",
    "comment": "mahishmathi",
    "timestamp": "2017-05-12 10:15:00"
}]

Add a new comment

POST /posts/1/comments
{
    "author": "bahubali",
    "comment": "mahishmathi",
}   
---
200 OK
{
    "id": 12,
    "author": "bahubali",
    "comment": "mahishmathi",
    "timestamp": "2017-05-12 10:15:00"
}

Get a comment

GET /posts/1/comments/12
---
200 OK
{
    "id": 12,
    "author": "bahubali",
    "comment": "mahishmathi",
    "timestamp": "2017-05-12 10:15:00"
}

Update a comment

PUT /posts/1/comments/12
{
    "id": 12,
    "author": "bahubali2",
    "comment": "do you know why kattappa killed bahubali?",
    "timestamp": "2017-05-12 10:15:00"
}
---
200 OK
{
    "id": 12,
    "author": "bahubali2",
    "comment": "do you know why kattappa killed bahubali?",
    "timestamp": "2017-05-12 10:15:00"
}

Delete a comment

DELETE /posts/1/comments/12
---
200 OK
{}

API - Tags (see v2)

Questions?

• How to find the post id from a comment?
• Is it a good idea to include comments in the representation of a post? How does it make sense when comment is a different resource type?

Blog API - v4

Simple RESTful API for managing blog posts.

Includes posts, tags, comments and authors.

Every post will have exactly is one author. For simplicity it is assumed that it can't be changed later.

Topics

The blog API v4 deals with the following resources.

• post
• tags
• comments
• authors

API - Posts

List Posts

GET /posts
---
200 OK
Content-Type: application/json

[{
    "id": 1,
    "author": {
        "id": 4
        "name": "Anand"
    },
    "title": "Hello World",
    "body": "My first blog post",
    "tags": ["hello"],
    "comments": []
}]

Get Post

GET /posts/1
---
200 OK
Content-Type: application/json

{
    "id": 1,
    "title": "Hello World",
    "body": "My first blog post",
    "tags": ["hello"],
    "comments": [],
    "author": {
        "id": 4
        "name": "Anand"
    }
}

Update Post

PUT /posts/1
{
    "id": 1,
    "title": "Hello World",
    "body": "My first blog post with some edits",
    "tags": ["hello"]       
}

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

{
    "id": 1,
    "title": "Hello World",
    "body": "My first blog post with some edits",
    "tags": ["hello"],
    "author": {
        "id": 4
        "name": "Anand"
    }
}

Delete Post

DELETE /posts/1
---
200 OK
Content-Type: application/json

{}

Create a Post

Since an author is always required to create a post, it would be easier, if can constuct

API - Authors

List authors

GET /authors
---
200 OK
[{
    "id": 1,
    "name": "Anand"
}]

Create an author

POST /authors

Get an author

GET /authors/1

Update an author

PUT /authors/1

Delete an author

DELETE /authors/1

List Posts of an author

GET /authors/1/posts

Create a new post

POST /authors/1/posts

{
    "title": "Building RESTful APIs",
    "body": "The workshop is today."
}
---
200 OK

{
    "id": 3,
    "title": "Building RESTful APIs",
    "body": "The workshop is today",
    "author": {
        "id": 1,
        "name": "Anand"
    }
}

API - Tags (see v2)

API - Comments (See v3)