2. What Does Your API Look Like? Flashcards
What are our resources in the context of a RESTful API design?
Anything anyone wants to interact with in our system. They are “nouns.”
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?
Note it down and carry on with the process, and when you have the chance, ask the product owner about it.
Having defined your resources, what is the next logical step?
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
• …
What is the HTTP method GET used for?
Retrieve a resource or a collection of resources.
What is the HTTP method DELETE used for?
Delete a resource.
What is the HTTP method PUT used for?
Update an existing resource.
What is the HTTP method POST used for?
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.
What HTTP method should you use for retrieving a list of resources?
GET
What HTTP method should you use for creating a resource?
POST
What HTTP method should you use for making a link between two existing resources or modify an existing link between them?
PUT
When designing a RESTful API, what should you not do in order to not cause a huge design problem?
Make things up — You should always ask the product owner what they want and never make assumptions.
What does an independent relationship mean in the context of RESTful APIs?
It means that the given resource can exist on its own without any other resources.
What does a dependent relationship mean in the context of RESTful APIs?
It means that the given resource can only exist if another resource already exists.
What does an associative relationship mean in the context of RESTful APIs?
It means that the given resource can be dependent or independent but needs additional information to describe the relationship.
What can be said about designing an API by exposing a database schema?
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.
What can be said about the interaction requirements of a RESTful API and a database schema for the same application?
The ways that people need to interact with your API don’t necessarily map one to one with your database.
What is the next step after having come up with the design and the structure of a RESTful API design?
Validate the API without wasting time, money, and effort. In other words, validate it without building it.
What is a quick and easy way to validate an API design?
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.
What is the best approach to validate an API design?
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.
What is the most common approach to validate an API design?
To write a documentation as if the API already existed.
What must an API documentation include?
- List of the endpoints and descriptions of what they do
- List of the parameters and descriptions of what they mean
- List of the response codes and descriptions of when you get each
- Response payload examples and payload fields
What is the goal of writing an API documentation?
To share it with other teams to have them accomplish their goals with our API.
What are the two common pitfalls when writing an API documentation for API design validation?
- 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.
- 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.
What is the biggest benefit of validating an API design by writing a documentation as if it existed already?
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.
