rest.md

Typical REST API design

Use nouns and ids to represent a resource

// OK
/users/1
/galleries/1/photos/23/comments

// prefer plural nouns, since GET /user Should respond with many users

Classic design

GET    /posts    // fetch all posts (you can use params for pagination, sorting and stuff - /posts?page=1)
GET    /posts/1  // fetch signle post with slug = 1
POST   /posts    // create a new post
PUT    /posts/1  // update post #1
PATCH  /posts/1  // the same - update post #1
DELETE /posts/1  // remove post #1

Use HTTP verb to indicate action

// GOOD
POST /users/1/articles
{...}

// BAD
POST /users/1/articles/create
{...}
GET  /users/1/articles/create?...

Common sense

Use custom slugs instead of ids

/users/1 // nah, it's very popular, but not ok for security, it's not readable, memorable
/users/easy_to_remember_username/gallery/vacation-2020 // good!

Use http

Learn about HTTP status codes and use them.

Responses examples

// bad
200 OK
{
  "status": "error",
  "data": {...}
}

// bad
200 OK
{
  "status": "ok",
  "data": {...}
}

// Good
200 OK
{
  "title": "...",
  // data
}

// Good
422 UNPROCESSABLE ENTITY
{
  "errors": {
    "title": "can't be blank"
  }
}

Also use headers from http - Content-Type, Authorization.