More on this book
Kindle Notes & Highlights
What would the consumer want to achieve by using the API? How can I make it easy for the consumer to find the API? How can I help the consumer to build apps with my API and make it convenient for the consumer to use the API?
An agile approach should only be used, until the API is published for the first time. Once the API has been published, changes need to be controlled more strictly and agility is confined to new versions of the API.
the complexity is dealt with in the client, the task of the API provider is simple and the task of the API consumer is difficult. This is usually the result of the inside-out approach and leads to sub-optimal APIs that make the life of the API consumer unnecessarily hard.
However, the task of the API consumer is simple. This is usually the result of the outside-in approach. An outside-in approach has a higher chance of producing APIs that consumers love and despite the difficulties for the API provider, it is the recommended approach.
Phase 1: Domain Analysis Phase 2: Architectural Design Phase 3: Prototyping
Phase 4: Implementing for Production Phase 5: Publishing Phase 6: Maintenance
Who are the consumers of the API? What is the purpose of the API? Which API solutions do the consumers plan to build with the API? Which other API solutions would be possible with the API?
To create a taxonomy, write down the usage scenario, then select the nouns in the text. Shortlist the nouns that would make sense as resources, i.e. nouns that describe data objects, which the operations create, read, update or delete can be performed on.
dependent resource cannot exist without the other. An independent resource on the other hand can exist without any other resource. Associative resources exist independently but still have some kind of relation, e.g. they may be connected by reference. The next step is to think about the states of the resources and possible transitions between the resource states.
The resources in the taxonomy have states and during the execution of the app, the resources may change their states and transition into new states. Express the states and transitions in a state diagram.
did we create a monster API? Does this API help us to realize our usage scenarios? Does the API follow the architectural style selected?
The API should deliver error messages that can be understood by the consumer. If the consumer made a mistake, the API provides hints for fixing the mistakes. The API should be forward compatible by handling unexpected input in a graceful way. Instead of throwing the hands up in the air and reject the request when a
small detail is incorrect, the API should deliver useful results anyway.
The API needs to ensure that it can only be accessed by authenticated and authorized consumers. The API does not leak internal information. The API is compliant with best practices and with security regulations.
Use of HTTP capabilities as far as possible. Design of resources (nouns), not methods or operations (verbs). Use of the uniform interface, defined by HTTP methods, which have well-specified semantics.
Stateless communication between client and server. Use of loose coupling and independence of the requests. Use of HTTP return codes. Use of media-types.
Information abstraction Simplicity Loose coupling Network efficiency Resource granularity
Convenience for the consumer Convenience for the provider
A resource is an abstraction of an HTTP entity, for example a website. A resource defines the abstract syntax of the entity; the concrete expression of the resource is called representation. A resource is addressable by a URI. One can interact with a resource via the Uniform HTTP
Use of HTTP capabilities as far as possible. Design of resources (nouns), not methods or operations (verbs). Use of the uniform interface, defined by HTTP methods, which have well-specified semantics. Stateless communication between client and server. Use of loose coupling and independence of the requests.
Use of HTTP return codes. Use of media-types.
model, lots of questions need to be answered. What should the scope of the resource be? Which attributes does it have? What is included and what not? How can the relationship to other resources be described? How can collections of resources be modeled?
A controller resource represents a long running process. An example would be a batch process for duplicate removal in the list of customers. It is available at the URL:
The access to collection resources typically contains modifiers, e.g. to filter resources with specific properties, to sort the resources, to group similar resources or to search for resources with specific properties. If no matching resources are found with filtering or searching, an empty collection is returned.
Sometimes, no sensible resource and standard HTTP method can be identified to describe a desired functionality. For example for triggering a batch process. Batch processes are typically long-running processes that run asynchronously.
this case, the functionality is modeled as a controller resource. It is triggered by a POST to the controller resource, which returns a status code 202 Accepted. This merely indicates that the process is submitted. Via location header in the response, the address of a newly created status resource is returned to the client. POST https://domain.com/customers/duplicateRemoval
> 202 Accepted Location: https://domain.com/customers/duplicateRemoval/502034 The status resource allows the client to track the status of the process. The status resource should include fields such as current status and the estimated execution time of the process. The status of the long running process can be obtained by a GET
on the status resource, usually by client-side polling. To make polling more efficient, the API can include a recommendation for the polling interval in the status representation. On completion of the process: Return status 303 See Other with a URL in the Location Header, pointing to the result produced by the process. GET https://domain.com/customers/duplicateRemoval
> 303 See Other Location: https://domain.com/customers On failure: Return 200 OK with an updated process resource, indicating the failure. GET https://domain.com/customers/duplicateRemoval/502034 -> 200 OK {
"error":"concurrent access" } Processing: Return 200 Ok with an updated process resource. GET https://domain.com/customers/duplicateRemoval/502034 -> 200 OK {
"progress":"20%", "estimated_time_to_completion":"5 min 4 sec" "polling_intervall":"20 sec" } An asynchronous delete can be implemented in a similar fashion via a control resource, except that the completion case does not return status code 303, but status code 200.
From the perspective of the API provider, the chosen granularity should optimize
the reusability of the resource. From the perspective of the API consumer, the chosen granularity should optimize (1) the simplicity, understandability and usability of the API as well as (2) the performance of the API. Any superfluous elements in the resource model should be avoided – but all the necessary elements should be included.
The URI uses only lower case characters. No camelCase or other use of capitals. URIs do not have a slash (“/”) as the last character. Use hyphens (“-”) to separate words and enhance readability. Do not use underscores (“_”). The URI does not contain any file extension. Resource names in the URI are plural nouns.
Do not use: Blanks: blanks are allowed according to IETF RFC 3986, but in practice they do confuse some clients. This is because form encoding and url encoding apply different rules (e.g. for blanks) Capital characters or camelCase: URLs are case-sensitive (except for protocol and host) according to IETF RFC
3986, but some clients cannot d...
This highlight has been truncated due to consecutive passage length restrictions.
Informational (1xx) status codes: Non-critical information. Success (2xx) status codes: The request was processed
successfully. Redirection (3xx) status codes: The client has to do another request based on the header parameters received in the response. Client Error (4xx) status codes: An error occurred. The client is responsible for the problem. Server Error (5xx) status codes: An error occurred. The server or API is responsible for the problem.
