Designing RESTful Web APIs

Question 1

What is the history of Distributed APIs? When REST came into play?

Answer 1

https://pasteboard.co/JsapZuZ.png

~ 2006

Question 2

What a simple http request is made of? How does the response look like?

Answer 2

a VERB, metadata and content. The response is status code, metadata and content.

Question 3

How long does a http request last? Is it correct to say that the http server is stateless?

Answer 3

As short as possible. Yes, stateless. A server will simply fullfil your request and forget about you.

Question 4

What are the 5 common verbs ir rest, which one updates just the necessary fields?

Answer 4

Get, post, put, delete and PATCH.

Question 5

What the request metadata consists of? Which are the most common keys? Which one is used to keep the state?

Answer 5

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

Question 6

What the request content consists of? What is the most common use of it?

Answer 6

HTML, CSS, JS, XML, JSON, BINARY/BLOBS and etc… it helps with information to fullfil the request.

Question 7

What the response status code consists of, what are the ranges and their meaning?

Answer 7

100~199: Informational (rarely used);
200~299: Success;
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).

Question 8

What the response headers consists of?

Answer 8

content-type, content-length, expires (cache: how long this data can be considered relevant), cookies (data sent previously in the request) and etc…

Question 9

What the response content consists of?

Answer 9

The response content can be anything as well: html, css, json, binary/blobs, apis can also have their own types.

Question 10

What is a good site to try rest?

Answer 10

arest.me

Question 11

What is REST and its main concepts? Who created it?

Answer 11

REpresentational State Transfer. Main concepts:

• Separation of client and server;
• Server requests are stateless;
• Cacheable requests;
• Uniform Interface;

Roy Fieldings

Question 12

What are the common problems of REST?

Answer 12

Too be difficult to be qualified as REST.. usually people tend to make shortcuts to create a pragmatic REST server

Question 13

What is a similarity between a REST server and WIKIPEDIA?

Answer 13

Both has URLS that show another URLs to further explore content.

Question 14

The endpoint should contain nouns or verbs?

Answer 14

NOUNS: api/customers

Question 15

What is a URI?

Answer 15

It is a unique (SINGLE) resource identifier:
/sites/1
/sites/stone-henge

Question 16

What is a query string? How to represent it?

Answer 16

allow developers to define how they are going to get this data.
/sites?sort=name
/sites?page=1

Question 17

What are the main differences between the http verbs applied to a list of items and a specific item?

Answer 17

can’t delete the whole collection; can’t post to a specific item (405)

Question 18

What idempotency means in the REST context? what is the only verb that is never idempotent?

Answer 18

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)

Question 19

Should I use .net specific stuff in the resturned JSON? What is the ultimate advice?

Answer 19

no… do platform agnostico.. e.g: json properties as camelCase. Be consistent… use the same rule everywhere.

Question 20

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?

Answer 20

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

Question 21

How the desired format is defined? what is the anti-pattern way?

Answer 21

The desired format can be defined in the headers. Avoid using query strings for that.

Question 22

What is hypermedia? When to use?

Answer 22

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.

Question 23

How to design associations? How to access all orders from a specific customers?

Answer 23

Means that the left side of the URL means some sort of relationship to objects.

e.g:
api/customer/123/orders

Question 24

How to avoid too many nested associations? What is the limit? api/customer/123/order/1/items/2/prices etc etc

Answer 24

By creating new endpoints? There is no limit, but should make sense by simply lookng at it.

Question 25

what does paging do? why is it important?

Answer 25

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

Question 26

What to do for error handling? do i need to include extra information other than the status code? When?

Answer 26

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.

Question 27

What is the HTTP caching and how it differs from server caching?

Answer 27

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

Question 28

How the usage on a ETag differs from a get to a post when it is stale?

Answer 28

A get will simply the the data again.. a post would return an error because the client no longer has the latest version

Question 29

What is a functional API? What does it have to do with pragmatism? Can I use common verbs to trigger functional API?

Answer 29

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

Question 30

What to use when we need a long-lived connection to the server? Should we use rest for that?

Answer 30

rest is not useful here... for this case it's best using gRCP, comet, signalR, Firebase and etc..

Question 31

Can I make breaking changes to my api after publishing? how to approach this?

Answer 31

no. use api versioning

Question 32

When to version the api?

Answer 32

When there are external users of the API other the team itself.

Question 33

How the api can be versionated? Cite 4 types;

Answer 33

url versioning: /api/v2/customers query string versioning: /api/customers?ver=2 header and content versioning

Question 34

What are the security considerations for an API?

Answer 34

Server security; Security in transit (ssl); Cors; auth

Question 35

What CORS stands for? Why does it do?

Answer 35

Cross origin resource sharing. It gives fine grained control over who can access the site via the browser (which domains can access which resources).

Question 36

What are the fours ways usually APIs are secured?

Answer 36

cookies, basic auth, token auth and oauth

Question 37

How does the token auth differs from basic auth?

Answer 37

client sends the creds less often once it uses the token most of the time until it expires.

Question 38

What is contained in a JSON web token (JWT)?

Answer 38

user information, claims, server signature, and other information.

Question 39

How does the server know the JWT was not modified, since it's pretty easy to change it because it's plain text?

Answer 39

because of the server signature.