The document discusses different types of APIs: System APIs, Process APIs, and Experience APIs. It then provides best practices for starting new API development, including designing the API, driven development, naming conventions, CRUD operations and HTTP verbs, status codes, and common error codes.
2. System API
System API are granular, self contained APIs build around standard function/operation
of system/application, database table/ procedures/views, CRUD operations,
represents single unit of work (UOW) with simple one-one datamapping. Any error
thrown from the API are send to the caller., error messages can be
technical. Transition errors like network connectivity can be retried for 3
times. System APIs are consumed by Process, Experience APIs, other Systems ,
Applications.
3. Process API
Process API are APIs that involves orchestration of one or more System APIs, complex
data transformation, integration of one or more systems etc. Process API represent
combination of multiple functions, operations. Error/Exception thrown from process
API should be self healing, meaningful error messages thrown to caller. Process APIs
can be consumed by Systems, Users, Applications. Process APIs are System API if its
reusable across enterprise
4. Experience API
Experience API are APIs that are build specific to
application/systems/end users , can have orchestration of one or more
System APIs, Processs APIs, has complex data
transformation, integration of one or more systems
etc. Error/Exception thrown from experience API should be self
healing, meaningful business error messages thrown to caller. System
APIs can be experience APIs as well.
5. Best practices to start New API development
• Design API
• Driven Development
• Naming convention for Resources
• CRUD and HTTP verb
• HTTP Status codes
• Common HTTP Error codes
6. Design API
The first and most basic step, is understanding what it is that you’re
actually building. Understand what your customers want (this means
involving them), understand what different types of APIs there are out
there, and why you are building the kind you are (REST, REST-like, SOAP,
RPC). Lastly, it’s important to map out the functionality that your users
need – and to not get stuck in a resources/CRUD mindset when doing
so.
7. Driven Development
Using a spec like RAML to model your API, lets you get an immediate
visual representation of what it is that you’re actually building while
taking advantage of code reuse and design patterns for consistency.
Keep your users involved and prototype (mock) your API for them to test
out using tools like the API Notebook. Keep making revisions to your
design until you have a solid foundation and have fixed 99% of the
design flaws. Then start building!
8. Naming for Resources
Keep your resources versatile and flexible. By using nouns you can stay
true to REST principles and avoid tightly coupling your resources to
methods or actions. Remember that you generally want your resources
in the plural form (users) and they should map to the objects or areas
that your clients are trying to manipulate (ie: /users to modify users).
9. CRUD and HTTP Verb
By thinking of actions in a Create, Read, Update, and Delete format you
can take advantage of the HTTP Action Verbs or methods and make it
easier for developers to utilize your API. Be sure to understand the
difference between POST, PUT, and PATCH – and when to use which.
10. HTTP Status codes
Tell your clients what’s happening, when things are successful (200, 201)
or when they’re not (304, 400, 500).
11. Common HTTP Error codes
Tell your clients what’s happening, or when they’re not (304,
400,404,405,401 500).
