Brainscape's Knowledge GenomeTM

Browse over 1 million classes created by top students, professors, publishers, and experts.


See full index

APIs: RESTful Design > 4. Common Design Challenges > Flashcards

4. Common Design Challenges Flashcards

1
Q

What are authentication and authorization commonly abbreviated as?

A

AuthN and AuthZ respectively.

How well did you know this?
1
Not at all
2
3
4
5
Perfectly
2
Q

What can authorization depend on?

A
  1. Identity
  2. Group membership
  3. Subscription level
  4. Context (time of day, location, device)
  5. Actions attempted
  6. …
How well did you know this?
1
Not at all
2
3
4
5
Perfectly
3
Q

What are the three most common API patterns for implementing authentication and authorization?

A
  1. API Keys
  2. Create Your Own Protocol
  3. OAuth 2.0
How well did you know this?
1
Not at all
2
3
4
5
Perfectly
4
Q

What are the benefits and drawbacks of using API Keys as a method of authentication and authorization?

A

Benefits:

  1. Framework and programming language agnostic
  2. Easy to add as a header or even to the URL

Drawbacks:

  1. URLs are convenient but logged everywhere (not a secret)
  2. Not easy to update/rotate if compromised
How well did you know this?
1
Not at all
2
3
4
5
Perfectly
5
Q

What are the benefits and drawbacks of creating your own protocol for authentication and authorization?

A

Benefits:
1. None! Do not do this under any circumstances, EVER

Drawbacks:

  1. Untested, unproven, supported by us
  2. Everyone needs training on it
  3. No supporting tools, ecosystems, or libraries
How well did you know this?
1
Not at all
2
3
4
5
Perfectly
6
Q

What is OAuth 2.0?

A

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.

How well did you know this?
1
Not at all
2
3
4
5
Perfectly
7
Q

What is the recommended API pattern for implementing authentication and authorization?

A

OAuth 2.0

How well did you know this?
1
Not at all
2
3
4
5
Perfectly
8
Q

What are the benefits and drawbacks of using OAuth 2.0 for API as the method of authentication and authorization in your APIs?

A

Benefits:

  1. Reliable and well-established
  2. Massive ecosystem
  3. Open-source and commercial options

Drawbacks:
1. Complicated and not easy to implement the first time

How well did you know this?
1
Not at all
2
3
4
5
Perfectly
9
Q

What are the two primary schools of thought for versioning an API, and what is the high-level practical difference between them?

A
  1. Versioning via Resource URL
  2. Versioning via Accept Header

Resource URL is easier and more explicit, whereas Accept Header is “proper.”

How well did you know this?
1
Not at all
2
3
4
5
Perfectly
10
Q

What does the Accept header specify in a HTTP request?

A

It specifies the formats that the client understands and asks the API to give back. This is called content negotiation.

How well did you know this?
1
Not at all
2
3
4
5
Perfectly
11
Q

What is content negotiation in its three levels?

A

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.

How well did you know this?
1
Not at all
2
3
4
5
Perfectly
12
Q

What is a media type in the context of content negotiation?

A

A well-defined structure that both the client and the server know how to handle.

How well did you know this?
1
Not at all
2
3
4
5
Perfectly
13
Q

What are the benefits and drawbacks of using the URL for API versioning?

A

Benefits:

  1. Clear and explicit
  2. Nothing is lost when you copy and paste

Drawbacks:
1. Is not considered “pure”

How well did you know this?
1
Not at all
2
3
4
5
Perfectly
14
Q

What are the benefit and the drawback of returning key-value pairs such as JSON from API endpoints?

A

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

How well did you know this?
1
Not at all
2
3
4
5
Perfectly
15
Q

What are media types in the context of API responses?

A

Media types allow us to use a commonly structured JSON file to move data back and forth.

How well did you know this?
1
Not at all
2
3
4
5
Perfectly
16
Q

What are the three most popular media types?

A
  1. Collection+JSON
  2. Hypertext Application Language (HAL)
  3. The Ion Hypermedia Type
17
Q

What are the characteristics of the Collection+JSON media type?

A
  1. Designed specifically to deal with groups or collections of resources
  2. Can also represent single items as a set of one
  3. In use, helper libraries and examples.
18
Q

What are the characteristics of the Hypertext Application Language (HAL) media type?

A
  1. Separates the payload into two parts — data and _links
  2. Can also represent single items as a set of one.
  3. Growing use, helper libraries and examples
19
Q

What are the drawbacks of the Hypertext Application Language (HAL) media type?

A
  1. Can be verbose (though not significantly so)
  2. Having metadata in _links separate from data is odd and this makes it easy to lose context and not explore as appropriate
20
Q

What are the characteristics of the Ion Hypermedia Type?

A
  1. Designed specifically to key data
  2. Metadata logically grouped and easier to process and apply
  3. Little use, fewer helper libraries and examples
21
Q

What does hypermedia mean?

A

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.

22
Q

What is content negotiation?

A

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.

23
Q

What is caching in the context of HTTP headers?

A

A way of storing and retrieving data so that future requests can retrieve it faster without performing an operation (calculation, network request, etc.) again.

24
Q

What HTTP header is used for caching, and how does it come about?

A

ETag, which is generated by the server and returned to the client.

25
Q

How does ETag work?

A
  1. Client makes a request.
  2. Server responds and creates an ETag based on resource state.
  3. Client makes a HEAD request (same request as before)
  4. If the data is unchanged, the server returns the same ETag — complete.
  5. If the data is changed, the server returns a new ETag.
  6. If the ETag is changed, the client recognises this and makes a full request.
26
Q

What can be said about distributing API documentation via PDF?

A

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.

27
Q

What is an important capability that a documentation versioning strategy should have to ease the process of figuring out what has changed for developers?

A

It should provide history and versioning information to provide the ability to compare the current documentation with the older ones.

28
Q

What should be our goals when creating API documentation?

A
  1. Code snippet friendly
  2. Provides page history, specifically user facing
  3. Easy to update
  4. Searchable — if we can’t find it, it doesn’t exist
29
Q

What are the benefits and the drawback of using Wikis for API documentation?

A

Benefits:

  1. Code snippets
  2. Page histories
  3. Easy to maintain
  4. Search friendly

Drawback:
It’s either updated or not — there’s no workflow or staging space in most systems.

30
Q

What are the benefits and the drawback of using Jekyll or other static site generators for API documentation?

A

Benefits:

  1. Code snippets via plugins
  2. Page histories via Git
  3. Easy to maintain
  4. Search friendly

Drawback:
You’re working in raw text or markup, which may be a challenge for your team.

APIs: RESTful Design (4 decks)

Brainscape helps you reach your goals faster, through stronger study habits.
© 2024 Bold Learning Solutions. Terms and Conditions