Flashcards in Designing RESTful Web APIs Deck (39)
What is the history of Distributed APIs? When REST came into play?
What a simple http request is made of? How does the response look like?
a VERB, metadata and content. The response is status code, metadata and content.
How long does a http request last? Is it correct to say that the http server is stateless?
As short as possible. Yes, stateless. A server will simply fullfil your request and forget about you.
What are the 5 common verbs ir rest, which one updates just the necessary fields?
Get, post, put, delete and PATCH.
What the request metadata consists of? Which are the most common keys? Which one is used to keep the state?
set of key, value pairs. content-type, content length, authorization, accept (what kind of data the client accept), cookies (passenger in the request, in order to keep some sort of state). Cookies keep the state
What the request content consists of? What is the most common use of it?
HTML, CSS, JS, XML, JSON, BINARY/BLOBS and etc... it helps with information to fullfil the request.
What the response status code consists of, what are the ranges and their meaning?
100~199: Informational (rarely used);
300~399: Redirection (asking you to look somewhere else);
400~499: Something is wrong with the request (client's fault);
500~599: Something is wrong with the server (server's fault).
What the response headers consists of?
content-type, content-length, expires (cache: how long this data can be considered relevant), cookies (data sent previously in the request) and etc...
What the response content consists of?
The response content can be anything as well: html, css, json, binary/blobs, apis can also have their own types.
What is a good site to try rest?
What is REST and its main concepts? Who created it?
REpresentational State Transfer. Main concepts:
- Separation of client and server;
- Server requests are stateless;
- Cacheable requests;
- Uniform Interface;
What are the common problems of REST?
Too be difficult to be qualified as REST.. usually people tend to make shortcuts to create a pragmatic REST server
What is a similarity between a REST server and WIKIPEDIA?
Both has URLS that show another URLs to further explore content.
The endpoint should contain nouns or verbs?
What is a URI?
It is a unique (SINGLE) resource identifier:
What is a query string? How to represent it?
allow developers to define how they are going to get this data.
What are the main differences between the http verbs applied to a list of items and a specific item?
can't delete the whole collection; can't post to a specific item (405)
What idempotency means in the REST context? what is the only verb that is never idempotent?
it means all the verbs should do the same thing over and over again without changing the result (except for post, post is never idempotent)
Should I use .net specific stuff in the resturned JSON? What is the ultimate advice?
no... do platform agnostico.. e.g: json properties as camelCase. Be consistent... use the same rule everywhere.
what to do when developing collections endpoints? should i return everything? what about adding extra information at root level of the object and the actual collection as a result object? What is the idea of the query string useWrapper?
should limit the amout of data returned and allow pagination. It is a good idea to add extra info to the root level of collection, such as count or next page url. The ideia is that the result will be put in the results collection
How the desired format is defined? what is the anti-pattern way?
The desired format can be defined in the headers. Avoid using query strings for that.
What is hypermedia? When to use?
Hypermedia add a new property called _links where it allows in an easier or even in an automated way the consumer to navigate the objects consistently. Use it when the complexity pays off.
How to design associations? How to access all orders from a specific customers?
Means that the left side of the URL means some sort of relationship to objects.
How to avoid too many nested associations? What is the limit? api/customer/123/order/1/items/2/prices etc etc
By creating new endpoints? There is no limit, but should make sense by simply lookng at it.
what does paging do? why is it important?
Allows users to query up to a maximum amount of data, after that the user needs to do another request to retrieve the rest of it. important to not send more data than necessary
What to do for error handling? do i need to include extra information other than the status code? When?
the api needs to return the error code and extra information when pertinent... e.g: title field is missing. 404 is clear enough by itself.
What is the HTTP caching and how it differs from server caching?
HTTP makes use of the ETag which is a key that is sent back and forth in order to know if the object that is being transmitted is the latest version of the object or if its invalidated
How the usage on a ETag differs from a get to a post when it is stale?
A get will simply the the data again.. a post would return an error because the client no longer has the latest version
What is a functional API? What does it have to do with pragmatism? Can I use common verbs to trigger functional API?
Functional API is an non-REST operation that is useful for the user, for the devs or even the sys admins to execute usefull things in the server... like reseed the database or flag a reboot. Usually the verb used is OPTIONS