2. What Does Your API Look Like?

Question 1

What are our resources in the context of a RESTful API design?

Answer 1

Anything anyone wants to interact with in our system. They are “nouns.”

Question 2

What should you do if there is a “hidden” resource in the process described for a RESTful API design that you’re not really sure what it is yet?

Answer 2

Note it down and carry on with the process, and when you have the chance, ask the product owner about it.

Question 3

Having defined your resources, what is the next logical step?

Answer 3

List out the actions that are applicable to each resource — not a complete list for the whole system, but only for the resources in question.

eg.
• List items
• List orders
• …

Question 4

What is the HTTP method GET used for?

Answer 4

Retrieve a resource or a collection of resources.

Question 5

What is the HTTP method DELETE used for?

Answer 5

Delete a resource.

Question 6

What is the HTTP method PUT used for?

Answer 6

Update an existing resource.

Question 7

What is the HTTP method POST used for?

Answer 7

Create a new resource, change the status/state of a resource, or anything else that doesn’t fit into the GET, DELETE, or PUT method.

Question 8

What HTTP method should you use for retrieving a list of resources?

Answer 8

GET

Question 9

What HTTP method should you use for creating a resource?

Answer 9

POST

Question 10

What HTTP method should you use for making a link between two existing resources or modify an existing link between them?

Answer 10

PUT

Question 11

When designing a RESTful API, what should you not do in order to not cause a huge design problem?

Answer 11

Make things up — You should always ask the product owner what they want and never make assumptions.

Question 12

What does an independent relationship mean in the context of RESTful APIs?

Answer 12

It means that the given resource can exist on its own without any other resources.

Question 13

What does a dependent relationship mean in the context of RESTful APIs?

Answer 13

It means that the given resource can only exist if another resource already exists.

Question 14

What does an associative relationship mean in the context of RESTful APIs?

Answer 14

It means that the given resource can be dependent or independent but needs additional information to describe the relationship.

Question 15

What can be said about designing an API by exposing a database schema?

Answer 15

That it’s a bad approach because fundamentally, the choices that go into designing your database are not the same choices that go into designing your API.

Question 16

What can be said about the interaction requirements of a RESTful API and a database schema for the same application?

Answer 16

The ways that people need to interact with your API don’t necessarily map one to one with your database.

Question 17

What is the next step after having come up with the design and the structure of a RESTful API design?

Answer 17

Validate the API without wasting time, money, and effort. In other words, validate it without building it.

Question 18

What is a quick and easy way to validate an API design?

Answer 18

Write code as if the API endpoint already exists. Don’t worry about whether the code compiles or not, but instead try to figure out if the API design makes sense.

Question 19

What is the best approach to validate an API design?

Answer 19

Use a microframework and actually develop the API in a minimal way in which it accepts incoming requests, validate the corresponding verbs and URL patterns, and returns static HTTP response codes and payloads.

Question 20

What is the most common approach to validate an API design?

Answer 20

To write a documentation as if the API already existed.

Question 21

What must an API documentation include?

Answer 21

1. List of the endpoints and descriptions of what they do
2. List of the parameters and descriptions of what they mean
3. List of the response codes and descriptions of when you get each
4. Response payload examples and payload fields

Question 22

What is the goal of writing an API documentation?

Answer 22

To share it with other teams to have them accomplish their goals with our API.

Question 23

What are the two common pitfalls when writing an API documentation for API design validation?

Answer 23

1. Most teams will want to make the documentation perfect. It should not be! Our goal must be to get feedback from other teams, partners, customers. We need a documentation that is clear and concise, but not perfect.
2. Some people will think that documentation is the last step of a project. When people see yours, they may believe you’re almost done with the API. Make sure to tell them that the documentation is for evaluation and validation, not for indicating that the development is complete.

Question 24

What is the biggest benefit of validating an API design by writing a documentation as if it existed already?

Answer 24

The documentation is almost done. Now, as you build the API, you can make sure to keep this documentation up to date and it’s a small marginal effort, not a massive effort at the end.