Implemented restful API for Wiredcraft User Table

[eronekogin]

The restful API provides general functions as follows:

• Could create/list/delete/update a general user record by following the standard restful api format.
• Could create/list/delete/check a user's followings and followers.
• Could list/check a user's friends.
• Could list the user's nearby friends according to the user address's geo coordinates.

• Has a global logging mechanism which records every network access requests together with application internal events.

  This application is created and unit tested by Ian Jiang (mengyu.jiang@gmail.com).

[MiffyLiye]

the http response status code is always 200, and has code 200, 201, 400, etc. in response body, which is not typical REST style, can you list the points that you think is essential for REST API design?

[eronekogin]

the http response status code is always 200, and has code 200, 201, 400, etc. in response body, which is not typical REST style, can you list the points that you think is essential for REST API design?

• In my understanding, the standard RESTFUL API design pattern lives in an ideal world and it requires the agreements between the application and the user as follows:

Standard REST API style:

• We should always use https protocol for the communications between the user and the api server.
• We should deploy the api under the specific domain like https://api.example.com.
• We should append the api's version number to the api's url like https://api.example.com/v1/users. Currently github follows this style.
• Each api url stands for a resource from the application and there should be no verb occurring in an api link.
• Then we use different HTTP methods to represent the actions we want to perform on the resource as follows:
  • GET: Fetch one or more instance of the target resource.
  • POST: Create a new resource.
  • PUT: Update an existing resource.
  • DELETE: Delete an existing resource.
• If the returned resources contain too many results, the api should provide filter parameters to the users and some normal parameters are as follows:
  • ?limit=10: Limit the amount of the returned resources to only 10 records.
  • ?page=2&pageSize=2: Paging the returned resources to contain only 2 records each page, then return the second page.
  • ?sortby=name&order=asc: Sorting the returned resources by the specified field name and order.
• The status code in the server response stands for the results from the api request:
  • 200 OK: Returned from GET method when the fetch is successful.
  • 201 CREATED: Returned from POST and PUT methods when the create/update is successful.
  • 204 NO CONTENT: Returned from DELETE method.
  • 400 INVALID REQUEST: Returned from POST/PUT methods when the delete is successful.
  • 401 Unauthorized: Returned when the user has no authorization to use this api.
  • 403 Forbidden: Returned when the user has been authorized but is not allowed to access this specific api.
  • 404 NOT FOUND: Returned when the user try to ask a resource which is not found on the server.
  • 422 Unprocesable entity: Returned from the POST/PUT methods when a validation error happens during create/update.
  • 500 INTERNAL SERVER ERROR: Returned when some application error happens on the server.
• If there is any error from the user request, the api should return error message as a json object in the body with error as key and the message text as value as follows:

{
    "error": "Error message text"
}

• For the server returning values when the action is success:

  • GET /collection: Return an array of resource objects.

  • GET /collection/resource: Return the single resource object.

  • POST /collection: Return the created resource object.

  • PUT /collection/resource: Return the updated resource object.

  • DELETE /collection/resource: Return an empty object.

  • It is also suggested to follow HATEOAS style when creating a restful api.

  • The server response should usually be in json format.

About the status code and response for the current version of this application:

• In real practice, some communication company like China Telecom will hijack the response with non-200 status code, for example, 404 and redirect them to the other pages. This could also happen when using some unethical browsers. So I believe it is a bit safer to return response code with status 200 and including the actual status code in the response object.
• So it is a strong suggestion to always use https protocols during communication between the users and the api server to prevent such hijacking.
• Once the https communications are implemented for this application together with user authroization/authentication function, I would be willing to enhance the current api response to follow the standard style.

[xavierchow]

Thanks all, that's good enough for our evaluation, I'm gonna close this PR.

@eronekogin We will reach out to you soon.