After reading tones of API success stories,many business & enterprises have started building their own API. While this sounds good, it also create problems in future if the design of the API is not well thought of. This blog throws light on the API design specifically for a business process.However, if you are very new to API and willing to start from level zero, then understand core principle of REST API before reading any further.
Resource is a central part of the API. Resource identifier, Resource representations, API operations everything are built around the resource. Anything is a part of a business can be seen as a resource.Virtual entities such as customer or vendor, non-virtual entities such as subscriptions or orders, business process such a employee on-boarding can be seen a resource.
Getting started with example
For the explanation point of view, lets select a employee on-boarding as a business process. We consider 4 different activities what business perform while on-boarding a employee.
- Creating employee
- Assigning a pay manager
- Creating a user account
- Create a email Inbox
All the above activities are performed in a sequence and are interrelated. For instance email inbox cannot be created without creating a user account.
The general approach
The most general approach is to develop resource which has CRUD operations for employee,user account,email Inbox and a custom operation to assign a pay manager. The implementation may look as below
| For employee GET /employee/GET /employee/1POST /employee/PUT /employee/DELETE /employee/ |
For user account GET /user_account/GET /user_account/1POST /user_account/PUT /user_account/DELETE /user_account/ |
For email inbox GET /email_inbox/GET /email_inbox/1POST /email_inbox/PUT /email_inbox/DELETE /email_inbox/ |
| For manager assignment POST /assign_manager/PUT /assign_manager/DELETE /assign_manager/ |
The drawbacks
The above approach seems to be perfect during development.However it introduces whole lot of problems and complexities when used by the API customer.Following are the major drawback in such approach
- API customer must have the knowledge of employee on-boarding process. In other words, the API provider migrate the business process logic to the API customer
- Introduces the API call sequence constrain. In other words, API customer must learn of which API call must be made after first one.
- After all, API fails to be successful because it is not developer friendly and needs more documentation and support hours
The right approach
One of the best approach is to treat the whole business process as one resource. Unlike having different resources like employee, user_account,email_inbox,assign_manager, here we create single resource and representation which has all the information needs to on-board an employee.Such implementation may look as below.
| GET /employee_onboard/GET /employee_onboard/1POST /employee_onboard/PUT /employee_onboard/
DELETE /employee_onboard/ |
To get all on-boarding processTo get a on-boarding process by IdTo start a new on-boarding processTo update a on-boarding process
To stop a on-boarding process |
Final Thoughts
API must not be developed;it must be designed. When API implementation considered as a design process one can come up with developer friendly API which needs minimal training and documentation.
Also Read : Should I build API early and make my product client of that API ?