Recommendations for simple COde Camp REST Implementations.

API_RECOMMEND.md

RESPONSE AND IMPLEMENTATION

1. Validation errors should return 422 response code.
2. Authentication errors should return 401 response code.
3. All request to save data should implement the POST http request method.
4. All request to update data should implement the PUT http request method.
5. All request to delete data should implement the DELETE http request method.
6. Successfull POST requests to create new records should return 201 response code.
7. Successfull GET requests should return 200 response code.
8. Successfull PUT, DELETE requests should return 202 response code.
9. If something goes wrong, return 400 response code.

EXTRA DATA

Provide the following data set in your response:

1. message: This should have an understandable reason for why you returned a specific response code or just OK for get requests with a data entity.
2. status: This should hold either of error, info, warning, or error depending on the response code or message.
3. code: This should be the same as the returned response code.
4. data: This should either be an an empty object or an object holding all the required data set.

SAMPLE RECOMMENDED RESPONSE

{
  "message": "OK",
  "status": "success",
  "code": 200,
  "data": {
    "user": {
      "username": "realralphg",
      "email": "[email protected]",
      "name": "Raphael Issah",
      "photo": "https://demosite.com/photos/realralphg/18236391_12312321_01278219.jpg"
    },
    "posts": []
  }
}

AUTHENTICATION

Registration and Authentication requests should return the same EXTRA DATA set as other requests with the addition of an authentication token.

{
  "message": "OK",
  "message": "Registration was successful",
  "status": "success",
  "code": 201,
  "token": "1|0912u312m312nn83z321noxsermxew34",
  "data": {
    "user": {
      "username": "realralphg",
      "email": "[email protected]",
      "name": "Raphael Issah",
      "photo": "https://demosite.com/photos/default.jpg"
    },
  }
}

AUTH IMPLEMENTATION

Authentication should be implemented by passing the authentication token as a Bearer token to the Authorization header property.

{
  "headers": {
    "Authorization": "Bearer 1|0912u312m312nn83z321noxsermxew34"
  }
}

USE NOUNS

Use plural nouns for collections, this plural naming convention becomes a global code. This also helps normal people to understand that these groups of APIs form a collection.

Collection	Role
/users	list all users
/users/123	specific user
/users/123/posts	list of posts that belong to a specific user
/users/123/posts/321	specific post of a specific users post list

DISCLAIMER

This document is only a recommendation and is subject to change without prior notice.

Author: 3m1n3nc3 for Greysoft Code Camp