几个增加 RESTful API 设计的可用性的技巧

Some Techniques for Better Usability in REST API Design

Someone said that API designers are UX engineers for developers. Good API design should be easy to use for consumers as well as easy to be implemented by developers.

Here are some techniques I summarized from my API design tasks. Let me know if it is helpful or you have more ideas on how to design a easy-to-use API.

Return 200 OK with Empty Array or 404 Not Found?

Problem

Sometimes, it is hard to tell if a GET API should return 200 OK with an empty array or it should return 404 not found. Actually, the answer is how the API client would like to handle it.

A 4XX response usually indicate there is something wrong in client’s request. Client also will treat it with a customized error page. Before an API designer makes a decision, it’s better to ask client developers how they will use the response.

Technique

However, there are common practice on which status code we should use. A API should return 200 OK with empty array if the purpose is to search records for a player or other criteria since an empty array isn’t an error caused by the client. It just means there isn’t any records of the player. However, the API should return 404 if the player cannot be found in the system because the client may entered a wrong player ID and the system should prompt this error to the user.

Example

Here is an example. In this example, the system tries to search active user sessions of a station. It returns 200 OK with an empty array while it returns 404 not found if station ID cannot be found.

Use controller or Use PUT to modify a resource?

Problem

In RESTful APIs, PUT is suggested to modify a resource but we also see APIs use controller with a POST for resource modification. Which way is better?

When you use put, you use body to wrap the object to be modified but the issue is we only need to change a status of an object, which is minimal change. You may confuse a developer in such case if you transfer an entire object to service for this purpose.

Technique

Use controller to minimize the number of parameters if you only want to change a status.

Example

You can see the difference between changing status of CPV (chip purchase voucher) with PUT and Controller.

PUT

The following images show the API use put to change a CPV status to redeemed and voided. The request body is CPVInfo object but you can see the only mattered properties are CPV ID, CPV status, and transaction info among all the properties. The API designer needs to tell developers which properties should be used in the API. This lowers usability of the API. The good news is that this make it easier to see transaction details if we need to analyze logs because the request body includes all the detail information of the CPV. We don’t need to reference other information source such as database.


Controller

The following example uses redeem and void controllers to redeem and void a CPV. You can see only transaction information is needed in request body. This makes much clear to API developers what parameters are actually should be used in the implementation. There isn’t CPV related parameters except CPV ID.

Use Read Only to specify properties that only should be shown in a response

Problem

Designers always want to reuse schemas to save their effort. For the above example, a CPVInfo object definition is used in both issue CPV API and redeem/void CPV API but not all properties of CPVInfo object are used in said APIs. Some properties should only be used in request and