REST - LinkedIn Learning Flashcards
Which are the broad steps for designing API?
API design is hard and is a game of tradeoffs.
1) Decide what functionality to expose by understading the domain and customer requirements
2) Decide how to expose it
3) Decide the best ways to expose it
4) Test and (in)validate the assumptions
5) Repeat
Which are the three different aspects in play when designing API?
1) What the API does
2) What the API makes easy
3) What the user wants to do
We need to strike balance and align these three to make a powerful API which is easy to use.
Example of coffee mug, suppose the mug didn’t have a handle then it tends to get hot, but after handle you can use it without burning your hand. The good thing about handle is that you can also use it to hang it on a hook.
How do we add an API?
There are three different scenarios
1) Bolt-On strategy - Brownfield. When you already have something running and you create API for that.
2) Greenfield Strategy - For new systems
3) Facade strategy
What is Bolt on strategy and what are pros and cons of Bolt on strategy?
Bolt on strategy is useful for existing applications when you already have an application and add an API after that fact.
Pros
1) Fastest way - Brute force approach
2) You have everything already running all the time
Cons
1) Bad naming conventions, architecture of the past get reflected in API and client libraries
What is Greenfield strategy and what are its pros and cons?
Greenfield strategy is useful for new systems where there is no application or business logic yet to interact with. We have complete flexibility to design API.
This is the “API first” or “Mobile First” approach.
Benefits
1) Easiest to develop API
2) Can take advantage of new technologies and architectures that reinvigorates the team.
Cons
1) Hardest option as there can be big gap from when you receive requirements and when you actually receive value from the system.
What is Facade strategy and what are pros and cons?
Facade is recommended approach, and is somwhere between greenfield and brownfield
We take advantage of existing system and yet shape them to what you prefer and need.
Benefits
1) Ability to rearchitect existing SOAP services with new REST interfaces.
2) The application is always functional, while making the underlying architecture better
Drawbacks
1) It can be challenging to have “multiple mindsets” in the system
2) There can be many conversion layers that can easily get out of control.
Steps for the API modelling process
1 - Identify the participants 2 - Identify Activities 3 - Break into steps 4 - Create API definitions 5 - Validate your API
Describe Step - Identifying the participants
Participants are the ones who will be involved in the business process that eventually uses the API. Participants are not only humans, they can be IoT devices, monitoring services etc also. So not all the participants will be humans.
Who/What is involved in our business process.
- Anyone who initiates the action
- Anyone who waits for an action to occur (receives action as a result of an event)
For each participant we need to understand
- Who they are (Give them a name and personna)?
- Are they internal or external (will it be used by other team in our organization or outside)?
- Are they active or passive participants?
What can be said about decision of system boundaries when designing API?
We should be very careful and clearly identify what we are responsible for and what are other, even third party coponents.
Describe Step - Identify Activities by taking an example of ordering a coffee
Revision 1 (Very simplistic view and abstract)
- Place an order
- Wait for the coffee
- You receive the order
The revision 1 does not go into the activities and the participants involved.
Revision 2
- The patron or you place the order with the cashier
- The cashier passes the order to the barista
- The barista acknowledges the order and adds it to the queue
- The cashier tells the patron their total bill
- Parton provides the payment, which is either accepted or rejected
- If rejected, patron needs to choose different payment method
- The barista makes the orders and delivers them to patron.
This paints much more complete picture of what is happening. It highlights the participants and the dependencies and the order in which actions occur.
Identifying participants and activities to order a book online
Identiying the participants of ordering book online process
- Customer
- System administrator (X) No role in this activity
- Developer (X) No role in this activity
- Stock Clerk (who fulfills the actual order)
- Customer support (just in case there is issue in ordering the book or the books are out of stock and inventory count is not accurate)
What are the activities?
1 - Customer searches for the book (so we need some mechanism for customer to search what he needs)
2 - The customer adds the book to their cart
3 - The customer adds more things? Removes things? (we need this functionality in future, but we are focused on ordering a book online. So we make a note document it that we will figure it out later and contact product owner to clarify things)
4 - The customer checks out
5 - The stock clerk retrieves and ships the book
6 - Customer support contacts the customer about the book in case it is out of stock and inventory details were not accurate, to either cancel the order or make some other arrangements.
So summary 1 - View items (search items) 2 - Add item to the cart 3 - Add more items? Remove items? 4 - Check out (including payment) 5 - Fulfill and ship the order 6 - View order
Describe the step - Creating API methods using example of ordering book online
First from the steps leave out the steps that are outside of scope of what you are tacking right now. This is where experience comes in and it more of a art.
FIND RESOURCES
Resources are anything someone wants to interact with in our system or another way is finding out NOUNS.
In book ordering case these are the resources
- Items (view, edit or add items) so similar to CRUD
- Cart - here we have design decision, either the cart is collection of items or is there a line item resource or object that holds individual item. We choose cart as collection of items. So adding or removing we just have to change the state of cart.
- Orders - order is simply a cart which has undergone the checkout process.
- Customer (hidden) - because to checkout we will need customer details but that detail we can figure out later and contact product owner about this.
We have not defined the checkout process, because it will be part of other story and will fill the details, currently we just know that checkout will either succeed or fail.
Which HTTP verb is used to get collection of resources?
HTTP GET is used for this. We should never modify information in this method.
Which HTTP verb is used for deleting?
HTTP DELETE is used for deleting resource
Which HTTP verb is used for updating the information of resource?
HTTP PUT is used for updating the existing resource
Which HTTP method is catch-all or default for something that doesn’t fit in any of methods?
HTTP POST is used for creation, to change the status/state of a resource. Used for anything which doesn’t cleanly map or fit the GET, PUT, DELETE verbs.
Define step - Creating API - Map the actions with HTTP verbs
Item resource
- Get Items (HTTP GET)
- Get Item (HTTP GET)
Cart resource (2 ways to see this - design and modelling decision)
1) Are we creating and then adding an item
- Create Cart (HTTP POST because we are creating a cart)
- Add item to Cart (HTTP POST because we are creating links between our cart and existing items)
- Check out
2) Are we creating a cart and then modifying the cart to add/remove items to it
- Create cart (HTTP POST because we are creating a cart)
- Add item to the cart (HTTP PUT because we are modifying the attributes of cart to add/remove item to it)
- Checkout (HTTP POST because it doesn’t cleanly fit into any of the GET, PUT, or DELETE verbs)
Order resource
- Create order (No need, probably done by checkout process)
- View order (HTTP GET)
- Cancel order (HTTP POST and not DELETE because we are not deleting the order but we are changing/modifying its status to cancelled)
Describe the types of relationships that resources can have
Independent
Can exist on its own without any other resources
Dependent
Can only exist if another resource already exists. Like in book ordering scenario, an order cannot exist without a cart previously existing.
Associative
Can be dependent or independent but needs additional information to describe it.
Describe the types of relationships between resources by taking example of movies and actors
Independent
Movies and Actors
are independent because we can one movie and one actor or we can have many movies and many actors.
Dependent
Movies and Characters
are dependent because a particular character cannot exist outside the movie.
Associative
One actor playing multiple characters in the same movie
or multiple actors playing role of same character (as teenager, child and adult). So just saying this actor plays this character isn’t enough, we need to say that this actor plays this character ‘as a child’ to fully understand.
Describe the types of relationships between resources by taking example of book ordering
Items are independent (don’t need cart or orders or customers to have items)
Cart is dependent on Items (can’t have a cart without items)
Orders are dependent on cart (only after we have a cart can we have order that is created by cart checkout process)
Orders are dependent on customers (there is actually a customer signed in who has ordered)
So by doing this exercise we get a dependency graph.
Is it a good practice to design API based on database design?
No it is not a good practice. Because first we are exposing the underlying database schema and secondly the choices that go into designing database are not same that go into designing API.
The ways with which people or customer interact with your API don’t map one to one with database.
Describe the step - Validating the API
Bad approach will be to start building the API to validate it. But it may waste months of efforts, so it’s a bad idea.
So we need a method to validate that is faster, cheaper.
1 - Post it cards/steps to map other use cases
If we can achieve other use cases with these steps then great, if not figure out which step is missing. After all we make these steps from activities, so everything must map cleanly together, if it doesn’t then that’s a red flag. We need to go steps back and make sure things work.
- Write code but not for API but client code which will behave as if API already existed. This will highlight major issus or structure issues.
- Use a microframework (hapi.js, slim in PHP) to create mock APIs (BEST APPROACH)
You can accept incoming requests and validate the verbs and URL patterns
We can send static HTTP response codes and payloads.
This appraoch is recommended because as we built things, we can start replacing those mock responses with real endpoints and watch things come together. - Documentation
Write the documentation as if the API already exisits.
- List endpoints - describe what they do
- List the parameters - describe what they mean
- List the response codes - describe when you get each
- Show the response payloads - define the fields
Goal is to write documentation that we can share with other teams that helps them in accomplishing their goals. It is good practice to include curl calls to show what calls look like.
But there are drawbacks of this approach
- Trying to be perfect. Instead we just need to be concise but not perfect.
- Documentation is last step, so people may think that the project is complete. So we need to clarify that documentation is for validation purposes.
