Design an API specification and import it to postman

6 min readNov 19, 2021

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.

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:

API Specification file:

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

Design an API specification and import it to postman

Designing an API specification :

API Specification file:

​Import the API specification in Postman

Written by Kirithika MJ

Import the API specification in Postman