Design to OpenAPI Spec

Let’s say you have been given this Dribble design. Your task is to write the API Spec for the "Top Collectibles" section of the page. The purpose of this task is to create the API recipe. The BE team needs to know how to create the API in a way that will serve the FE needs. First, take in what you see and write down the pieces of data and their data type that you think will be needed to create this UI. I see information like the image as a string, ETH number, number of likes, the title as a string, and the creator with its own properties of image as a string and username as a string. This is not a complete list since I would have to ask the designer or product team what the string of “Ofspace NFT” with the check mark represents. My rough draft notes would look something like this.

• What type of request is it asking for (GET, POST, PUT, PATCH, DELETE)?

• Is the request dependent on any other information provided (user id, email, password, etc)? The answer to this question is/are the parameter/s for the request.

• Should the parameters be query, body, or path? Read about API Parameters

• Are the parameters required?

• What is the goal of the request? What is needed out of it? The answer is the API response.

• What is the happy response and message that should be given to the client?

• What is the potential error response and message that should be given to the client?

Open up Swagger Editor. It comes with a PetStore API written by their team.

• Come up with an endpoint name that clearly communicates the purpose and place it under the paths object. I’m going to use  /collectibles.

• Next add the HTTP Method. For this assignment it should be GET.

• Add the directory that it belongs to as a tag. I’m adding a tag called nft to the tags object.

• Write a brief summary and description of what the endpoint accomplishes and any information that the users of the specification might need to know.

• Next up add any parameters if necessary.

• Add the responses now. Remember that you want at least one success and one failed response. HTTP Responses

• See the /store/inventory endpoint to understand formatting a response with an example. You will want to reference a schema called Collectible which you will write in the next step $ref: "#/components/schemas/Collectible"

• Scroll down the section called components/schema and here is where you get to use your notes from the design breakdown section. Create schemas for Collectible and Creator. You can view your schemas by scrolling down the page to the Schema section and toggling them open. Review them to make sure they are what you want.

• Pay attention to the errors that may come up in the Swagger Editor and make changes accordingly.

• Your team may want you to add your API Specifications to a yaml file and submit the changes for review.