Design an API specification and import it to postman

To develop an API, first step is to design an API specification. For any specification, we should gather requirements first. Today, am going to write an API specification for McDonald's menu . In order to write this specification, we can use a simple text editor

like a notepad or a word pad.

I have written this specification for McDonald's burger menu using openAPI.

My menu has four fields in it: name,price,description,toppings.

1)name : Big Mac,

price:50,

description: Mouthwatering perfection starts with two 100% pure beef patties and sauce sandwiched between a sesame seed bun,

toppings: pickles, crisp shredded lettuce, finely chopped onion and American cheese

2)name : Cheese burger,

price:20,

description: classic cheeseburger begins with a 100% pure beef burger seasoned with just a pinch of salt and pepper,

toppings: tangy pickle, chopped onions, ketchup, mustard, and a slice of melty American cheese

3)name : Ham burger,

price:40,

description: 100% pure beef burger seasoned with just a pinch of salt and pepper,
 toppings: tangy pickle, chopped onions, ketchup and mustard

4)name : McDouble,

price:30,

description: 100% pure beef burger seasoned with just a pinch of salt and pepper,
 toppings: tangy pickle, chopped onions, ketchup, mustard, and a slice of melty American cheese.

​

Let's dive in. The following steps are crucial to design and import.

-> Designing an API specification

-> Import the API specification in Postman

​

​

Designing an API specification :

There are different types of API's. Today am using open api to design this specification.

This is the standard header for an openapi specification :

openapi: 3.0.1
 info:
 title: McDonald's Menu
 description: Displays the Menu
 version: '1.0'
 servers:
  - url: http://localhost:3000/menu/api/v1

I have mentioned the url as localhost for the time being.

To design a specification file, the following steps should be defined.

Step 1 : The endpoints

Step 2 : Requests for each endpoint

Step 3 : Responses for each endpoint

Step 4 : Parameters and schema for each endpoint

​

Step 1 : The endpoints

In the above example, am defining 2 endpoints.

I) list of all the items - /items

II) list or alter a single item - /items/{itemId}

Note: The / and the {} are standard way of representing the endpoints.

Step 2 : Requests for each endpoint

For each endpoints mentioned above, let's define the request method. Typically API allows Create,Read,Update,Delete(CRUD) operation.

Create -> Post Request -> To create a new item

Read -> Get Request -> To retrieve all items/an item using itemId

Update-> Put Request -> To update a particular item using itemId

Delete -> Delete Request -> To delete an existing item using itemId

openapi: 3.0.1
 info:
  title: McDonald's Menu
  description: Displays the Menu
  version: '1.0'
 servers:
  - url: http://localhost:3000/menu/api/v1
 paths:
  /items:
  get:
  description: Gets the list of all items for the current user
 /item:
  post:
  description: Creates a new item
 /item/{itemId}:
  get:
  description: Gets the information for the specified item
  put:
  description: Changes the description for the specified item
  delete:
  description: Removes the specified item

​

Step 3 : Responses for each endpoint

Each request made should be followed by a response with codes, either positive( 200 OK,201 Created,204 no content) or negative response( 400 error). Also, the content type of the application should be defined. Am defining content type as JSON .

​

openapi: 3.0.1
 info:
 title: McDonald's Menu
 description: Displays the Menu
 version: '1.0'
 servers:
 - url: http://localhost:3000/menu/api/v1
 paths:
  /items:
  get:
  description: gets the list of all items for the current user
  responses:
  '200':
  description: got back the list of items
  content:
  application/json
  '400':
  description: sent wrongly formatted data
  content:
  application/json
 
  /item:
  post:
  description: create a new item
  responses:
  '201':
  description: created a new item
  content:
  application/json
  '400':
  description: sent wrongly formatted data
  content:
  application/json
 
  /item/{itemId}:
  get:
  description: Gets the information for the specified item
  responses:
  '200':
  description: Got back the specified item
  content:
  application/json
  '400':
  description: sent wrongly formatted data
  content:
  application/json
  put:
  description: Changes the description for the specified item
  responses:
  '200':
  description: item updated correctly
  content:
  application/json
  '400':
  description: send wrongly formatted data
  content:
  application/json
  delete:
  description: Removes the specified item
  responses:
  '204':
  description: specified item removed
  content:
  application/json
 
 

Step 4 :Parameters and schema for each endpoint

There are various kinds of parameter available like path, query, etc., In this example, am defining a path parameter itemId(which is also an endpoint).

Sample path parameter :

/item/{itemId}:
  get:
  description: Gets the information for the specified item
  parameters:
  - in: path
  name: itemId
  description: Id of the item
  required: true
  example:
  itemId: 1

Note : The field required:true under description means that it must be specified.

​

Let's set up the schema next. A schema is a set of rules that dictate what the response should look like. This schema is based on JSON specification. Similar to functions used in any programming language, we can define schema under components and reference it to any request.

Schema/rules:

--> itemId should be of integer type and a min value of 1

--> item should have a required name and price

--> individual data type for every item is described as:

i) name - type string

ii) price - type integer

iii) description - type string

iv) toppings - type string

/itemId:
  type: integer
  minimum: 1
  example: 1
 /item:
  type: object
  required:
  - itemName
  - price
  properties:
  itemName:
  type: string
  price:
  type: integer
  description:
  type: string
  toppings:
  type: string

With the definition of parameters and schema and setting up the references, our completely designed API specification file looks like:

openapi: 3.0.1
 info:
  title: McDonald Menu
  description: Manages McDonald burgers
  version: '1.0'
 servers:
  - url: http://localhost:5000/menu/api/v1
 paths:
  /items:
  get:
  description: gets the list of all items for the current user
  responses:
  '200':
  description: got back the list of items
  content:
  application/json:
  schema:
  $ref: '#/components/schemas/items'
  '400':
  description: sent wrongly formatted data
  content:
  application/json:
  schema:
  $ref: '#/components/schemas/Error'
  /item:
  post:
  description: create a new item
  responses:
  '201':
  description: created a new item
  content:
  application/json:
  schema:
  $ref: '#/components/schemas/item'
  '400':
  description: sent wrongly formatted data
  content:
  application/json:
  schema:
  $ref: '#/components/schemas/Error'
  requestBody:
  $ref: '#/components/requestBodies/itemBody'
  /item/{itemId}:
  get:
  description: Gets the information for the specified item
  parameters:
  - in: path
  schema:
  $ref: '#/components/schemas/itemId'
  name: itemId
  description: Id of the item
  required: true
  example:
  itemId: 1
  responses:
  '200':
  description: Got back the specified item
  content:
  application/json:
  schema:
  $ref: '#/components/schemas/item'
  '400':
  description: sent wrongly formatted data
  content:
  application/json:
  schema:
  $ref: '#/components/schemas/Error'
  put:
  description: Changes the description for the specified item
  parameters:
  - in: path
  schema:
  $ref: '#/components/schemas/itemId'
  name: itemId
  description: Id of the item
  required: true
  responses:
  '200':
  description: item updated correctly
  content:
  application/json:
  schema:
  $ref: '#/components/schemas/item'
  '400':
  description: sent wrongly formatted data
  content:
  application/json:
  schema:
  $ref: '#/components/schemas/Error'
  requestBody:
  $ref: '#/components/requestBodies/itemBody'
  delete:
  description: Removes the specified item
  parameters:
  - in: path
  schema:
  $ref: '#/components/schemas/itemId'
  name: itemId
  description: Id of the item
  required: true
  responses:
  '204':
  description: specified item removed
  content:
  application/json:
  schema:
  type: object
 components:
  requestBodies:
  itemBody:
  required: true
  content:
  application/json:
  schema:
  $ref: '#/components/schemas/item'
  schemas:
  itemId:
  type: integer
  minimum: 1
  example: 1
  item:
  type: object
  required:
  - itemName
  - price
  properties:
  itemName:
  type: string
  price:
  type: integer
  description:
  type: string
  toppings:
  type: string
 
  items:
  type: array
  items:
  $ref: '#/components/schemas/item'
  Error:
  type: string
  default: "Bad data sent"

​

Save the above file as McDonald.yml extension. Hurray! our file is now ready to be added/imported.

​

Import the API specification in Postman

To import:

1. Open Postman, select API on the left tab and click on import.

2.Upload the McDonald.yml file and choose "TestSuite" under "Link this collection as"
  dropdown.

​

3. On pressing Import, you should see a collection and an API with name " McDonald menu".

4. Click the McDonald API dropdown and choose draft. On the right side, under Overview click "View Schema".

5. Our API specification is imported successfully and is ready for testing.

Alternatively, we can create a Collection and click Overview-> Schema and try to copy paste the text file as well.

Happy reading!!

Reference : API Testing and Development with Postman by Dave Westerveld