API Design (RESTful) & Naming Convention

Reference Specs

• Header value: application/vnd.api+json

JSON:API — A specification for building APIs in JSON

GitHub - json-api/json-api: A specification for building JSON APIsGitHub

Query Specs

Structure

${class} [ ${property} ] =${value} 

e.g)
page[number]=1&page[number]=3

filter

• filter[${MODELNAME}]=val1,val2,valN...

• filter[${MODELNAME}]=${FIELD_NAME}:${VALUES}:${TYPE}:${OPERATOR}

filter[articles]=
    field1:['type-a','type-b','type-c','type-d']:string:in,
    isActive:true:boolean:eq

page

• page[number,size]

page[number]=1,page[size]=25

field

• field[${MODELNAME}]=attr1,attr2,attrN...

field[article]=field1,field2
&field[picture]=filed3,field4

include

• include[${MODELNAME}]

include=article,picture

sort

• sort[${MODELNAME}]=-filed1,filed2

sort[article]=-created,title
# desc created, asc title

type	class	property
Nested	page	number size	Pagenation
Simple	include	N/A
Nested	filter	${MODEL_NAME}	filter[post]=1,2&filter[author]=12 HTTP/1.1

root
|- nested
|    |- simple
|    |- simple
|    |- simple
|
|-simple     

Create

Get, GetList

pagination

https://jsonapi.org/examples/#pagination

page[number]=1&page[size]=3

GET /articles?page[number]=3&page[size]=1 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "meta": {
    "totalPages": 13
  },
  "data": [
    {
      "type": "articles",
      "id": "3",
      "attributes": {
        "title": "JSON:API paints my bikeshed!",
        "body": "The shortest article. Ever.",
        "created": "2015-05-22T14:56:29.000Z",
        "updated": "2015-05-22T14:56:28.000Z"
      }
    }
  ],
  "links": {
    "self": "http://example.com/articles?page[number]=3&page[size]=1",
    "first": "http://example.com/articles?page[number]=1&page[size]=1",
    "prev": "http://example.com/articles?page[number]=2&page[size]=1",
    "next": "http://example.com/articles?page[number]=4&page[size]=1",
    "last": "http://example.com/articles?page[number]=13&page[size]=1"
  }
}

Update, bulk update

delete, bulk delete

Filter (where)

field (Attribute)

include

include & attributes

JSON:API — Examples

GET /articles?include=author HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!",
      "body": "The shortest article. Ever.",
      "created": "2015-05-22T14:56:29.000Z",
      "updated": "2015-05-22T14:56:28.000Z"
    },
    "relationships": {
      "author": {
        "data": {"id": "42", "type": "people"}
      }
    }
  }],
  "included": [
    {
      "type": "people",
      "id": "42",
      "attributes": {
        "name": "John",
        "age": 80,
        "gender": "male"
      }
    }
  ]
}

GET /articles?include=author&fields[articles]=title,body,author&fields[people]=name HTTP/1.1

GET /articles?include=author
&fields[articles]=title,body,author
&fields[people]=name HTTP/1.1

Filtering

JSON:API — Recommendations

GET /comments?filter[post]=1,2&filter[author]=12 HTTP/1.1

```
"filter=field1:['type-a','type-b','type-c','type-d']:string:in,isActive:true:boolean:eq";


"filter=
    field1:['type-a','type-b','type-c','type-d']:string:in,
    isActive:true:boolean:eq";
    
    

"filter[articles]=
    field1:['type-a','type-b','type-c','type-d']:string:in,
    isActive:true:boolean:eq";
```

/products/{products_id}/product-topics?filter[products]=isActive:true:boolean:eq&page[number]=1&page[size]=3

filter[product-topics]=is_positive:true:boolean:eq

{column_name}:{value}:{type}:{operator}

User {
  age: int
}

/users?filter[user]=age:20:integer:gt

= gt = greater than

https://sequelize.org/master/manual/model-querying-basics.html

sorting

JSON:API — Latest Specification (v1.0)

bad(official) example

GET /articles?sort=-created,title HTTP/1.1

good example

GET /articles?sort[article]=-created,title HTTP/1.1

{
  "data": [{
    "type": "articles",
    "id": "1",
    "id_type": "uuid" | "integer"
    "attributes": {
      "title": "JSON:API paints my bikeshed!"
    },
    "links": {
      "self": "http://example.com/articles/1"
    },
    "relationships": {
      "author": {
        "links": {
          "self": "http://example.com/articles/1/relationships/author",
          "related": "http://example.com/articles/1/author"
        },
        "data": { "type": "people", "id": "9" }
      },
      "comments": {
        "links": {
          "self": "http://example.com/articles/1/relationships/comments",
          "related": "http://example.com/articles/1/comments"
        },
        "data": [
          { "type": "comments", "id": "5" },
          { "type": "comments", "id": "12" }
        ]
      }
    }
  }],
  "included": [{
    "type": "people",
    "id": "9",
    "attributes": {
      "first-name": "Dan",
      "last-name": "Gebhardt",
      "twitter": "dgeb"
    },
    "links": {
      "self": "http://example.com/people/9"
    }
  }, {
    "type": "comments",
    "id": "5",
    "attributes": {
      "body": "First!"
    },
    "relationships": {
      "author": {
        "data": { "type": "people", "id": "2" }
      }
    },
    "links": {
      "self": "http://example.com/comments/5"
    }
  }, {
    "type": "comments",
    "id": "12",
    "attributes": {
      "body": "I like XML better"
    },
    "relationships": {
      "author": {
        "data": { "type": "people", "id": "9" }
      }
    },
    "links": {
      "self": "http://example.com/comments/12"
    }
  }]