4. Common Design Challenges Flashcards
What are authentication and authorization commonly abbreviated as?
AuthN and AuthZ respectively.
What can authorization depend on?
- Identity
- Group membership
- Subscription level
- Context (time of day, location, device)
- Actions attempted
- …
What are the three most common API patterns for implementing authentication and authorization?
- API Keys
- Create Your Own Protocol
- OAuth 2.0
What are the benefits and drawbacks of using API Keys as a method of authentication and authorization?
Benefits:
- Framework and programming language agnostic
- Easy to add as a header or even to the URL
Drawbacks:
- URLs are convenient but logged everywhere (not a secret)
- Not easy to update/rotate if compromised
What are the benefits and drawbacks of creating your own protocol for authentication and authorization?
Benefits:
1. None! Do not do this under any circumstances, EVER
Drawbacks:
- Untested, unproven, supported by us
- Everyone needs training on it
- No supporting tools, ecosystems, or libraries
What is OAuth 2.0?
It’s an authorization protocol. It doesn’t define how you authenticate, just that you must authenticate with a trusted entity. The access token you then get back describes or internally maps to a description of what actions you are or are not allowed to perform.
What is the recommended API pattern for implementing authentication and authorization?
OAuth 2.0
What are the benefits and drawbacks of using OAuth 2.0 for API as the method of authentication and authorization in your APIs?
Benefits:
- Reliable and well-established
- Massive ecosystem
- Open-source and commercial options
Drawbacks:
1. Complicated and not easy to implement the first time
What are the two primary schools of thought for versioning an API, and what is the high-level practical difference between them?
- Versioning via Resource URL
- Versioning via Accept Header
Resource URL is easier and more explicit, whereas Accept Header is “proper.”
What does the Accept header specify in a HTTP request?
It specifies the formats that the client understands and asks the API to give back. This is called content negotiation.
What is content negotiation in its three levels?
It’s the process of establishing the markup/notation for an API endpoint to return. This is done by an Accept header and is usually established as XML or JSON.
At the next level, the media type may also be established, which practically means the structure of the markup (XML/JSON).
At the third and final level, the version of the media type and the resource may also be established.
What is a media type in the context of content negotiation?
A well-defined structure that both the client and the server know how to handle.
What are the benefits and drawbacks of using the URL for API versioning?
Benefits:
- Clear and explicit
- Nothing is lost when you copy and paste
Drawbacks:
1. Is not considered “pure”
What are the benefit and the drawback of returning key-value pairs such as JSON from API endpoints?
Benefit:
It’s incredibly easy to consume.
Drawback:
It becomes harder to extend and impossible to add detail about the data as it gets more and more complex
What are media types in the context of API responses?
Media types allow us to use a commonly structured JSON file to move data back and forth.
What are the three most popular media types?
- Collection+JSON
- Hypertext Application Language (HAL)
- The Ion Hypermedia Type
What are the characteristics of the Collection+JSON media type?
- Designed specifically to deal with groups or collections of resources
- Can also represent single items as a set of one
- In use, helper libraries and examples.
What are the characteristics of the Hypertext Application Language (HAL) media type?
- Separates the payload into two parts — data and _links
- Can also represent single items as a set of one.
- Growing use, helper libraries and examples
What are the drawbacks of the Hypertext Application Language (HAL) media type?
- Can be verbose (though not significantly so)
- Having metadata in
_linksseparate from data is odd and this makes it easy to lose context and not explore as appropriate
What are the characteristics of the Ion Hypermedia Type?
- Designed specifically to key data
- Metadata logically grouped and easier to process and apply
- Little use, fewer helper libraries and examples
What does hypermedia mean?
It means that the media in question is non-linear. Think of a “choose your own adventure” book — you don’t start from page one and make your way onto the last page sequentially.
What is content negotiation?
The mechanism that allows different versions of the same document to exist at a single URL so the client and the server can determine which version best fits their needs.
What is caching in the context of HTTP headers?
A way of storing and retrieving data so that future requests can retrieve it faster without performing an operation (calculation, network request, etc.) again.
What HTTP header is used for caching, and how does it come about?
ETag, which is generated by the server and returned to the client.
How does ETag work?
- Client makes a request.
- Server responds and creates an ETag based on resource state.
- Client makes a HEAD request (same request as before)
- If the data is unchanged, the server returns the same ETag — complete.
- If the data is changed, the server returns a new ETag.
- If the ETag is changed, the client recognises this and makes a full request.
What can be said about distributing API documentation via PDF?
Don’t do it. You’ll have the problem of having multiple versions floating around, no one knowing which version is right, and your customers never knowing if things are quite right.
What is an important capability that a documentation versioning strategy should have to ease the process of figuring out what has changed for developers?
It should provide history and versioning information to provide the ability to compare the current documentation with the older ones.
What should be our goals when creating API documentation?
- Code snippet friendly
- Provides page history, specifically user facing
- Easy to update
- Searchable — if we can’t find it, it doesn’t exist
What are the benefits and the drawback of using Wikis for API documentation?
Benefits:
- Code snippets
- Page histories
- Easy to maintain
- Search friendly
Drawback:
It’s either updated or not — there’s no workflow or staging space in most systems.
What are the benefits and the drawback of using Jekyll or other static site generators for API documentation?
Benefits:
- Code snippets via plugins
- Page histories via Git
- Easy to maintain
- Search friendly
Drawback:
You’re working in raw text or markup, which may be a challenge for your team.
