EMSA :: WEB APIs DESIGN BEST PRACTICES

This is used for our internal design & implementation

0
182

Part I: OVERVIEW

What is API design?

  • Allows the interaction between two applications using a set of rules.
  • To simplify the creation of software by reusable
  • “A point where two systems,subjects, organizations, etc. meet and interact”
  • “each API only exposes one function, this is only to keep the figure as simple as possible”

Design an API for its users

  • Avoiding the provider’s perspective and focus on the consumer’s one
  • Can be understood at first sight.
  • Easy-to-use and easy-to-understand, Focus on what users can do with it
  • Viewing an API as software’s control panel, (like a button, when press, it do a specific purpose… read labels, turn knobs.)
  • The API is what users see; it is a representation of what they can do.
  • We need to think about the consumer first when designing an API.
  • In order to be easy for consumers to understand and use, an API must be designed from the consumer’s perspective.
  • Identifying users, what they can do, how they do it, what they need to do it, and what they get in return is the key to building a comprehensive API goals list.

REST: Representational State Transfer

To be RESTful — a software architecture needs to conform to the six following constraints:

  • Client/server separation: One request handled by as least one service.
  • Statelessness. Server and client do not cache the state of each other.
  • Cacheability -> to reduce the server handling (client – cache – server)
  • Layered system: middleware – reduce the complication and easy to scale
  • Uniform interface: Each server can create a standard to simplify the way client interact with server and many types of client can interact – Such as the concepts

Part II: DESIGN REST APIs

The URL is a sentence, where resources are nouns and HTTP methods are verbs

Identifying resources and their relations

  • Resources may or may not have relations to other resources. A resource may contain some other resources of the same type. Such a resource is called a collection resource or simply collection .  e.g: thingtypes/xxx/things
  • The following  APIs are not good designed because: Verbs should not appear in the url path:
    • DELETE      /sapi/iot/things/removeThingsFromGroups
    • GET             /sapi/iot/things/getGroups
    • DELETE     /sapi/iot/things/deleteThingGroup/:id
  • Should use plural nouns:
    • e.g: use /sapi/users instead of /sapi/user

REST URI convention – Singular or plural name of resources

It is better to have a schema that you can map directly to code (easy to automate), mainly because code is what is going to be at both ends

  • GET  /orders                 <—> orders 
  • POST /orders                <—> orders.push(data)
  • GET  /orders/1              <—> orders[1]
  • PUT  /orders/1               <—> orders[1] = data
  • GET  /orders/1/lines    <—> orders[1].lines
  • POST /orders/1/lines  <—> orders[1].lines.push(data) 

Identifying actions and their parameters and returns (cont.)

CRUD – POST/GET/PUT/PATCH/DELETE

  • The PATCH HTTP method can be used to partially update a resource.
  • The PUT HTTP method can be used to totally replace an existing resource, or to create a nonexisting one and provide its identifier.

Identifying actions and their parameters and returns (cont.)

Action is the goal’s main verb and applies to the goal’s main resources

XPAAS
‘POST   /sapi/iot/things-data/latest’: ‘ThingDataController.getThingDataNewest’,

Should be:

‘GET   /sapi/iot/things-data/latest?thingId=xxx&thingId=yyy&thingId=yyy’:  ‘xxx’,

-> problem: url max length = ?

Identifying actions and their parameters and returns (cont.)

Representing resources with paths:

  • Unique
  • Explicit
  • May contain an ID
  • Should reflect hierarchy
  • Should reflect collection resource’s item type

Identifying actions and their parameters and returns (cont.)

A GET HTTP request’s parameters are usually provided as query parameters in the path. e.g: GET /example?param1=value1&param2=value2

Designing the API’s data

Designing concepts (Projection): Design concept of data (required or optional properties) that have some meaning with user.

For example: USER concept should only include: username, firstname, lastname, … the metadata property should not be visible to user

Designing responses from concepts

While “add product” and “get product” should return the complete product, “search for  products” may return only a reference , name , price , and the supplier’s name as supplierName

DESIGN CHALLENGES

Select the right action:

User checkout cart: we have 2 options: (Each user has one cart only)
/cart/check-out
/check-out-cart
So what is the action should be used? Your confusing here:
POST: default recommended -> can be used when we have no choice
GET: We think that no param should be send to server in this case -> so the get method make this API look simple?
PATCH: The cart status should be update to CHECKING_OUT?
DELETE: When the cart checked-out, an order is created instead. So we have to remove all item in the carts or delete this cart?

Answer: We must ask ourselves a few questions:

  • What are we trying to represent?
  • What happens in this use case?
  • What happens when we check out a cart?

-> Well, an order is created that contains all the cart’s products. And after that the cart is emptied
-> That’s it! We are creating an order ! Therefore, we can use a POST /orders request to create an order and check out cart.

Handle Feedbacks

  • Any representation must be easily understandable by humans and programs
  • Any representation must be as informative as possible
  • An error feedback must provide enough elements to understand and maybe fix the problem
  • A success feedback must describe what has been done

Grouping multiple errors in one feedback

To reduce the number of request/error cycles

For example, API to create User need as least 2 information (username, email).
If both of them is not provided, the error should be:

{ …
Code: 400,
Message: “bad request”,
Errors: [{…
Message: “”Username is mandatory”
},
{ …
Message: “”Email is mandatory”
}]

Returning informative success feedback

  • A simple OK is usually not enough
  • A success feedback should provide information about what happened

Part III: PREDICTABLE API (COMING SOON)

Part IV: ORGANIZABLE API (COMING SOON)

Part V: SECURE API (COMING SOON)

Part VI: NETWORK –  EFFICIENT API (COMING SOON)

Part VII: DESIGNING IN CONTEXT (COMING SOON)

LEAVE A REPLY

Please enter your comment!
Please enter your name here