Web API Design Architecture

Recently, I have been busy with a mobile project involving integrating with APIs provided by PHP. Be honest, it is not that difficult to design and develop APIs, no matter what computer languages you are adopting.  The challenging part of the process is to design it in a way that follows http standards.

After looking into the provided documentation, I found out a few design issues. 

(1) Http Methods

Firstly, I was surprised to see all the api functions are invoked via HTTP Method - POST. REST styled web services have gained popularity for the last a couple of years, and most developers are fully aware of the importance of adhereing HTTP standards. Though this api architecture is not REST, different HTTP methods (or at least GET, POST) should be used to identify the purpose of the operation. 

1. GET - should be used while fetching data from the resource server, such as GetProduct.

2. POST - should be used while inserting data 

3. PUT - should be used while updating data

4. DELETE - should be used while deleting data 

In this case, as the design is not rest styled, GET and POST are enough. 

 

(2) authentication

Authentication and authorization are both important process to secure the server resources. 

There are a few popular approaches when comes to the authentication.

1. First one is basic authentication, and the design is pretty straightfoward. User information including name and password are embeded into the HTTP authorization header with base64 encoded. Then the api server is using the header info to perform authentication and authorization. But as the data is only encoded in Base64 format, the process is only secure through HTTPS protocol. The advantage of this approach is simplicity, easy to develop, test and debug. On the other hand, as every request is involving passing sensitive info (name & password) to api, there is the risk of data get comprimised. 

 

2. At the moment, most api providers such as twitter, google have suspended the basic authentitcation and switched to a more secure approach OAuth 2.0 which was originally created in late 2006, providing specific authoriation flows for web application, desktop application and mobile phones. The basic process flow of OAuth 2.0 is as following.  

The authentication process is as following:

1. Client sends authorization request to resource owner.

2. If success, the client will receive authoriztion grant. 

3. Client send authorization grant to the authorization server, and recieve the Access token

4. Client then use access token to get resources from Resource server. 

 

(3) HTTP response

Http status code is used to identify the result of one single http request. 200, 201, 400, 401, 404, 500 are common status code and well known by developers. In jquery, the sucess api call back is based on the status code betwee 200 and 300. So, returning status code accroding to standards is very important. 

However, the current api design return status code 200 all the time. And it returns custom defined error code and error message while an error is occurring. I agree with that custom error code can be used to provide more detailed info about the specific exception, but it has to be within proper status code context.