API Design Process Flashcards
What can be said about consumers of API, are they machine to machine or people on other side?
In the API space, we build something on a machine for a machine to use and this is wrong because there are people on the other side of API clients.
Define UX honeycomb which has 7 adjectives.
APIs should be
1) Useful
Is the API useful from end user’s point of view?
2) Usable
Can the API be quickly used by a developer and provide easy-to-use functionality?
3) Desirable
Is the functionality provided by the API something that generates desire in developers and end users?
4) Findable
Can the API documentation be found easily, and can developers tart using it immediately?
5) Acessible
Can the API provide functionality for end users who have technical constraints/limitations in consuming it?
6) Credible
Is the data provided by the API trustworthy?
7) Valuable
Does the API contribute to the company’s bottom line and improve customer satisfaction?
What do we mean by
Designing the right thing?
Designing the thing right?
1) Designing the right thing?
This phase is split into Discover/Research and Define/Synthesis. While designing something new it is very easy for people to blow the actual scope of the problem and put all their effort into designing something that no one actually wants or will use. This phase of designing keeps us grounded and makes sure we are designing for the right thing by doing diligent research and defining the right problem statement to solve.
1.1) Discover/Research
- Gain domain knowledge.
- Understand what problem we are trying to solve
- Who are stakeholders
- Use-cases and the requirements
- Existing solutions and approaches
- Talk to all stakeholders
- 2) Define/Synthesis
- Give structure to raw data gathered from previous step
- Try finding trends that span across multiple use-cases
- Find dependencies to other services, like other microservice
- Identify all the Resources for which we need APIs
- Outline behavior and expectations of APIs
- Identify amount of business logic that will be in service or client
2) Designing the thing right
- 1) Develop/Ideation
- From previous step we are clear what needs to be done
- OpenAPI/Swagger are great to describe important aspects of API
- Especially the frontend design decisions and architectural decisions can be captured using API description languages as they are visible to user
- Import swagger, OpenAPI or RAML specification files into Postman Collection
- API documentation, Different API scenarios/states, Prototype using tools like Postman - 2) Deliver/Implementation
- Establish contract tests first so that if anything changes they start failing
- If its a bug or legitimate change, you can update the code or inform the affected teams.
What do we mean by
Designing the right thing?
Designing the thing right?
1) Designing the right thing?
This phase is split into Discover/Research and Define/Synthesis. While designing something new it is very easy for people to blow the actual scope of the problem and put all their effort into designing something that no one actually wants or will use. This phase of designing keeps us grounded and makes sure we are designing for the right thing by doing diligent research and defining the right problem statement to solve.
1.1) Discover/Research
- Gain domain knowledge.
- Understand what problem we are trying to solve
- Who are stakeholders
- Use-cases and the requirements
- Existing solutions and approaches
- Talk to all stakeholders
Why is there need to build Design Style Guide for APIs?
When team grows new people joining start applying their own conventions when naming endpoints, use of headers, query parameters, response structures etc. In such scenario how to ensure quality and consistency.
Even UI design teams face such challenges and they solve this by creating design style guide which make sure that everyone in the team uses the same UI component etc.
Companies like Google, Paypal have design style guides.
Which is best way to learn API designing?
1) Create a lot of APIs
2) Read existing APIs and design practices resources
https: //www.getpostman.com/api-network/
https: //community.apigee.com/spaces/123/index.html
What is the job of API?
The API’s job is to make application developer as successful as possible.
What should be the primary design principle when designing API?
It should be to maximize application developer productivity and success.
Which are API design elements?
1) The representations of your resources
definition of fields in the resources (assuming structured data as opposed to stream of bytes or chars) and links to related reources
2) The use of standard HTTP headers (occasionally custom headers)
3) The URLs and URI templates
that define the query interface of your API for locating resources based on their data.
4) Required behaviors by clients for example DNS caching behaviors, retry behaviors, tolerance of fields that were not previously present in resources and so on.
What can be said about REST and state of resource?
In REST model, a web resource has underlying state, which cannot be seen directly , and what flows between clients and servers is a representation of that state. Users can view representation of a resource in different formats, called media types. In principle, all media types for the representation of a particular resource should encode the same information just in different formats.
Which is the de-facto standard for representing resource in Web APIs and why?
JSON is de-facto. It is because it is easy to understand and easy to map to the programming data structures of Javascript and other languages.
Limitations of JSON
It cannot represent many data types. Null, Boolean, String, Number. Dates and times are not supported.
What guidance should be followed to keep JSON simple
Names/keys in the JSON are always property names and the JSON objects always correspond to entities in your API’s data model.
Example that follows this advice:
{
"kind": "Dog",
"name": "Lassie",
"furColor": "brown"
}
Example that does not follow this advice
{
"user-id-1": {
"data" : [
{
"id": "12345",
"picture": "url"
}
]
}
}
This one is hard to learn. data field is artifact of JSON design and not a property on User resource.
Which is the construct used in HTTP to represent relationships?
Link is the natural construct in HTTP to represent relationships.
Why is HATEOAS (Hypermedia As The Engine Of Application State) viewed as impractical?
Because generic clients are usually less satisfactory, especially clients with a User interface, so such API is rarely built.
How HATEOAS helps API?
the realization that the use of links brings a significant
improvement to the usability and learnability of all APIs, not just those that are designed to be consumed
by completely general-purpose clients.
Example of JSON with relationship links
{
"id": "098123",
"kind": "dog",
"name": "Lassie",
"furColor": "Brown",
"ownerLink": "https://dogtracker.com/persons/12093"
}
{
"id": "123",
"name": "Joe",
"hairColor": "Brown",
"kind": "Person",
"dogLink": "https://dogtracker.com/persons/1234/dogs"
}
URI templates or Path params use?
URI templates are most useful if they accept variables whose values are easy for humans to read and remember. For example
https://dogtracker.com/persons/{personId}
is not good because it is hard to remember the obscure and length identifier.
But compared to above one
http://dogtracker.com/persons/{personName}
is more useful because names are fundamental way in which humans deal with world.
In the dog tracking example we included link to owner using ownerId property which worked well. Now what to do if the owner can be an individual or an institution?
We have a few options,
First we could have ownerID and supplement it with ownerType property.
Or we can have separate personOwnerID or institutionalOwnerId out of which any one will be set at a time.
We could also have a compound owner value that can incorporate the type and the id.
Most elegant and flexible solution to this is having owner property of type url.
{
…,
“owner” : “https://dogtracker.com/persons/123213”
}
or
{
…,
“owner” : “https://dogtracker.com/institutions/1122
}
So owner property is now read-write rather than read-only. We can accommodate both individual and institution by changing the URL. Clients have to be aware that the owner URL may point to different sorts of resources and they have to be prepared to react differently.
Should we store URLs with domain name and scheme in database?
No we should not store absolute url which contains domain name in database, because if domain name changes in some circumstances then DB will have to be updated. Also we want freedom to use same database in different environments (integration test, system test, pre-production) with different domain names. This means we will have to strip the scheme and authority from URLs before storing in DB and add back when requested.
What is one of solution to avoid problems storing URLs in database?
To use path absolute URLs that start with /. So the URLs will be relative paths. The only tradeoff is that it introduces burden on client to turn those relative URLs into absolute before using them.
Give some example of URI Templates that we can send in response so that client can process it
{
“following_url”: “https://api.github.com/users/octocat/following{/other_user}”,
“gists_url”: “https://api.github.com/users/octocat/gists{/gist_id}”,
“starred_url”: “https://api.github.com/users/octocat/starred{/owner}{/repo}”,
}
Give some example of URI Templates that we can send in response so that client can process it
{
“following_url”: “https://api.github.com/users/octocat/following{/other_user}”,
“gists_url”: “https://api.github.com/users/octocat/gists{/gist_id}”,
“starred_url”: “https://api.github.com/users/octocat/starred{/owner}{/repo}”,
}
Explain Permalinks
Any link that a server puts in the representation of a resource can be bookmarked, stored by the client,
and used later. This means that you need to try to make it stable.
There is some good advice on the web on how to design stable URLs.
“After the creation date, putting any information
in the name is asking for trouble one way or another.”
