Appendix C - Example Interface Specification

The following illustrates a sample API Interface Specification. The specification is written in Swagger and visualised here (for readability) via a Confluence plugin however most API Developer Portal products will support importing OpenAPI specifications.

Illustration of an Example Agency API

Illustation of modifiy customer 

Illustration of create customer 

 

The raw JSON and YAML is below. This is best viewed via the Swagger editor http://editor.swagger.io/#/

To view, simply open the OpenAPI editor as above and paste the contents of the JSON or YAML examples into the editor window.

JSON

{

    "swagger": "2.0",

    "info": {

        "version": "2.0.0",

        "title": "Example Agency API",

        "description": "A sample API specification demonstrating OpenAPI capabilities - this is for example purposes only",

        "termsOfService": "https://developer.example.govt.nz/termsandconditions/",

        "contact": {

            "name": "Example Agency API team",

            "email": "exampleteam@api.govt.nz",

            "url": "https://agency.govt.nz"

        }

    },

    "host": "api.example.govt.nz",

    "basePath": "/v2",

    "paths": {

        "/customers/{customerId}": {

            "get": {

                "parameters": [

                    {

                        "name": "customerId",

                        "in": "path",

                        "description": "Unique ID of customer",

                        "required": true,

                        "type": "string"

                    }

                ],

                "tags": [

                    "get customer details"

                ],

                "description": "Returns details for a customer given a unique customer ID\n",

                "security": [

                    {

                        "AuthorizationCode": [

                            "customerRead"

                        ]

                    }

                ],

                "produces": [

                    "application/json"

                ],

                "responses": {

                    "200": {

                        "description": "OK - Successful",

                        "schema": {

                            "$ref": "#/definitions/customerDetailsResponse"

                        }

                    },

                    "default": {

                        "description": "Error response",

                        "schema": {

                            "$ref": "#/definitions/errorModel"

                        }

                    }

                }

            },

            "put": {

                "tags": [

                    "modify customer"

                ],

                "description": "Updates a customer’s details",

                "consumes": [

                    "application/json"

                ],

                "produces": [

                    "application/json"

                ],

                "parameters": [

                    {

                        "name": "customerId",

                        "in": "path",

                        "description": "Unique ID of customer",

                        "required": true,

                        "type": "string"

                    },

                    {

                        "name": "body",

                        "in": "body",

                        "required": true,

                        "schema": {

                            "$ref": "#/definitions/customerRequestModel"

                        }

                    }

                ],

                "responses": {

                    "200": {

                        "description": "Updated resource successfully"

                    },

                    "default": {

                        "description": "Error response",

                        "schema": {

                            "$ref": "#/definitions/errorModel"

                        }

                    }

                },

                "security": [

                    {

                        "AuthorizationCode": [

                            "customerWrite"

                        ]

                    }

                ]

            },

            "delete": {

                "tags": [

                    "delete customer"

                ],

                "description": "Deletes an existing customer resource",

                "consumes": [

                    "application/json"

                ],

                "produces": [

                    "application/json"

                ],

                "parameters": [

                    {

                        "name": "customerId",

                        "in": "path",

                        "description": "Unique ID of customer",

                        "required": true,

                        "type": "string"

                    }

                ],

                "responses": {

                    "200": {

                        "description": "Deleted resource successfully"

                    },

                    "default": {

                        "description": "Error response",

                        "schema": {

                            "$ref": "#/definitions/errorModel"

                        }

                    }

                },

                "security": [

                    {

                        "AuthorizationCode": [

                            "customerDelete"

                        ]

                    }

                ]

            }

        },

        "/customers": {

            "post": {

                "tags": [

                    "create customer"

                ],

                "description": "Creates a new customer. API will create a customer resource and, if successful, return a hyperlink to the created resource",

                "consumes": [

                    "application/json"

                ],

                "produces": [

                    "application/json"

                ],

                "parameters": [

                    {

                        "name": "body",

                        "in": "body",

                        "required": true,

                        "schema": {

                            "$ref": "#/definitions/customerRequestModel"

                        }

                    }

                ],

                "responses": {

                    "201": {

                        "description": "Created resource successfully",

                        "schema": {

                            "$ref": "#/definitions/_links"

                        }

                    },

                    "default": {

                        "description": "Error response",

                        "schema": {

                            "$ref": "#/definitions/errorModel"

                        }

                    }

                },

                "security": [

                    {

                        "AuthorizationCode": [

                            "customerCreate"

                        ]

                    }

                ]

            }

        }

    },

    "securityDefinitions": {

        "AuthorizationCode": {

            "type": "oauth2",

            "scopes": {

                "customerRead": "Grants read access to a customer resource",

                "customerWrite": "Grants write (update) access to an existing customer resource",

                "customerCreate": "Grants access to create a new customer resource",

                "customerDelete": "Grants access to delete an existing customer resource"

            },

            "flow": "accessCode",

            "authorizationUrl": "https://idm.example.govt.nz/oauth/authorize",

            "tokenUrl": "https://idm.example.govt.nz/oauth/access_token"

        }

    },

    "definitions": {

        "customerRequestModel": {

            "type": "object",

            "properties": {

                "names": {

                    "type": "object",

                    "properties": {

                        "firstName": {

                            "type": "string",

                            "description": "Customers first name"

                        },

                        "middleName": {

                            "type": "string",

                            "description": "Customers middle name"

                        },

                        "lastName": {

                            "type": "string",

                            "description": "Customers last name"

                        },

                        "salutation": {

                            "type": "string",

                            "description": "Customers salutation - e.g. Mr John Doe"

                        },

                        "title": {

                            "type": "string",

                            "description": "Customers title - e.g. Ms, Mr, Mrs, Dr etc."

                        }

                    }

                },

                "addresses": {

                    "type": "array",

                    "description": "An array of addresses. Unpopulated properties or items will be returned as null JSON objects.",

                    "items": {

                        "properties": {

                            "addressType": {

                                "type": "string",

                                "description": "Address type - e.g. Home, Business"

                            },

                            "address1": {

                                "type": "string",

                                "description": "First line of the address e.g. 2 something street"

                            },

                            "address2": {

                                "type": "string",

                                "description": "Second line of address e.g. Khandallah"

                            },

                            "address3": {

                                "type": "string",

                                "description": "Third line of address e.g. Wellington"

                            },

                            "address4": {

                                "type": "string"

                            },

                            "country": {

                                "type": "string",

                                "description": "This is a human readable country name e.g. New Zealand and not a country code"

                            }

                        }

                    }

                }

            }

        },

        "customerDetailsResponse": {

            "type": "object",

            "required": [

                "customerId"

            ],

            "properties": {

                "customerId": {

                    "type": "string",

                    "description": "Unique identifier for the customer resource - GUID format"

                },

                "names": {

                    "type": "object",

                    "properties": {

                        "firstName": {

                            "type": "string",

                            "description": "Customers first name"

                        },

                        "middleName": {

                            "type": "string",

                            "description": "Customers middle name"

                        },

                        "lastName": {

                            "type": "string",

                            "description": "Customers last name"

                        },

                        "salutation": {

                            "type": "string",

                            "description": "Customers salutation - e.g. Mr John Doe"

                        },

                        "title": {

                            "type": "string",

                            "description": "Customers title - e.g. Ms, Mr, Mrs, Dr etc."

                        }

                    }

                },

                "addresses": {

                    "type": "array",

                    "description": "An array of addresses. Unpopulated properties or items will be returned as null JSON objects.",

                    "items": {

                        "properties": {

                            "addressType": {

                                "type": "string",

                                "description": "Address type - e.g. Home, Business"

                            },

                            "address1": {

                                "type": "string",

                                "description": "First line of the address e.g. 2 something street"

                            },

                            "address2": {

                                "type": "string",

                                "description": "Second line of address e.g. Khandallah"

                            },

                            "address3": {

                                "type": "string",

                                "description": "Third line of address e.g. Wellington"

                            },

                            "address4": {

                                "type": "string"

                            },

                            "country": {

                                "type": "string",

                                "description": "This is a human readable country name e.g. New Zealand and not a country code"

                            }

                        }

                    }

                },

                "_links": {

                    "type": "array",

                    "description": "An array of related links relevant to the request/response.",

                    "items": {

                        "properties": {

                            "rel": {

                                "type": "string",

                                "description": "A piece of information providing context for the link - e.g. self or accounts."

                            },

                            "href": {

                                "type": "string",

                                "description": "A fully qualified URL to the resource."

                            }

                        }

                    }

                }

            }

        },

        "errorModel": {

            "type": "object",

            "properties": {

                "errors": {

                    "type": "array",

                    "items": {

                        "description": "An array of error items containing error codes and descriptions. Note that the error descriptions will be normalised.",

                        "properties": {

                            "code": {

                                "type": "integer",

                                "format": "int32",

                                "description": "An error code - should be used in conjunction with the HTPP response code."

                            },

                            "description": {

                                "type": "string",

                                "description": "A short description of the error."

                            }

                        }

                    }

                },

                "_links": {

                    "type": "array",

                    "items": {

                        "properties": {

                            "rel": {

                                "type": "string",

                                "description": "The relationship to the request e.g. self which contains the resource that was requested or {object name}, a link to a resource that is related to the requested resource"

                            },

                            "href": {

                                "type": "string",

                                "description": "A link to the related resource. In an error scenario this is likely to be something such as a link to a support portal."

                            }

                        }

                    }

                }

            }

        },

        "_links": {

            "type": "array",

            "items": {

                "properties": {

                    "rel": {

                        "type": "string",

                        "description": "The relationship to the request e.g. self which contains the resource that was requested or {object name}, a link to a resource that is related to the requested resource"

                    },

                    "href": {

                        "type": "string",

                        "description": "A link to the related resource"

                    }

                }

            }

        }

    }

}

YAML

#Example API Specification for Agency X

#Author Swithin Foote Middleware New Zealand

swagger: '2.0'

info:

  version: 2.0.0

  title: Example Agency API

  description: A sample API specification demonstrating OpenAPI capabilities - this is for example purposes only

  termsOfService: https://developer.example.govt.nz/termsandconditions/

  contact:

    name: Example Agency API team

    email: exampleteam@api.govt.nz

    url: https://agency.govt.nz

host: api.example.govt.nz

basePath: /v2

paths:

  /customers/{customerId}:

    get:

      parameters:

        - name: customerId

          in: path

          description: Unique ID of customer

          required: true

          type: string

      tags:

        - get customer details

      description: |

        Returns details for a customer given a unique customer ID

      security:

        - AuthorizationCode:

            - customerRead

      produces:

        - application/json

      responses:

        200:

          description: OK - Successful

          schema:

            $ref: '#/definitions/customerDetailsResponse'

        default:

          description: Error response

          schema:

            $ref: '#/definitions/errorModel'

    put:

      tags:

        - modify customer

      description: Updates a customer’s details

      consumes:

        - application/json

      produces:

        - application/json

      parameters:

        - name: customerId

          in: path

          description: Unique ID of customer

          required: true

          type: string

        - name: body

          in: body

          required: true

          schema:

            $ref: "#/definitions/customerRequestModel"

      responses:

        200:

          description: Updated resource successfully

        default:

          description: Error response

          schema:

            $ref: '#/definitions/errorModel'

      security:

        - AuthorizationCode:

          - customerWrite

    delete:

      tags:

        - delete customer

      description: Deletes an existing customer resource

      consumes:

        - application/json

      produces:

        - application/json

      parameters:

        - name: customerId

          in: path

          description: Unique ID of customer

          required: true

          type: string

      responses:

        200:

          description: Deleted resource successfully

        default:

          description: Error response

          schema:

            $ref: '#/definitions/errorModel'

      security:

        - AuthorizationCode:

          - customerDelete

  /customers:

    post:

      tags:

        - create customer

      description: Creates a new customer. API will create a customer resource and, if successful, return a hyperlink to the created resource

      consumes:

        - application/json

      produces:

        - application/json

      parameters:

        - name: body

          in: body

          required: true

          schema:

            $ref: "#/definitions/customerRequestModel"

      responses:

        201:

          description: Created resource successfully

          schema:

            $ref: '#/definitions/_links'

        default:

          description: Error response

          schema:

            $ref: '#/definitions/errorModel'

      security:

        - AuthorizationCode:

          - customerCreate

securityDefinitions:

  AuthorizationCode:

    type: oauth2

    scopes:

      customerRead: Grants read access to a customer resource

      customerWrite: Grants write (update) access to an existing customer resource

      customerCreate: Grants access to create a new customer resource

      customerDelete: Grants access to delete an existing customer resource

    flow: accessCode

    authorizationUrl: https://idm.example.govt.nz/oauth/authorize

    tokenUrl: https://idm.example.govt.nz/oauth/access_token

definitions:

  customerRequestModel:

    type: object

    properties:

      names:

        type: object

        properties:

          firstName:

            type: string

            description: Customers first name

          middleName:

            type: string

            description: Customers middle name

          lastName:

            type: string

            description: Customers last name

          salutation:

            type: string

            description: Customers salutation - e.g. Mr John Doe

          title:

            type: string

            description: Customers title - e.g. Ms, Mr, Mrs, Dr etc.

      addresses:

        type: array

        description: An array of addresses. Unpopulated properties or items will be returned as null JSON objects.

        items:

          properties:

            addressType:

              type: string

              description: Address type - e.g. Home, Business

            address1:

              type: string

              description: First line of the address e.g. 2 something street

            address2:

              type: string

              description: Second line of address e.g. Khandallah

            address3:

              type: string

              description: Third line of address e.g. Wellington

            address4:

              type: string

            country:

              type: string

              description: This is a human readable country name e.g. New Zealand and not a country code

  customerDetailsResponse:

    type: object

    required:

    - customerId

    properties:

      customerId:

        type: string

        description: Unique identifier for the customer resource - GUID format

      names:

        type: object

        properties:

          firstName:

            type: string

            description: Customers first name

          middleName:

            type: string

            description: Customers middle name

          lastName:

            type: string

            description: Customers last name

          salutation:

            type: string

            description: Customers salutation - e.g. Mr John Doe

          title:

            type: string

            description: Customers title - e.g. Ms, Mr, Mrs, Dr etc.

      addresses:

        type: array

        description: An array of addresses. Unpopulated properties or items will be returned as null JSON objects.

        items:

          properties:

            addressType:

              type: string

              description: Address type - e.g. Home, Business

            address1:

              type: string

              description: First line of the address e.g. 2 something street

            address2:

              type: string

              description: Second line of address e.g. Khandallah

            address3:

              type: string

              description: Third line of address e.g. Wellington

            address4:

              type: string

            country:

              type: string

              description: This is a human readable country name e.g. New Zealand and not a country code

      _links:

        type: array

        description: An array of related links relevant to the request/response.

        items:

          properties:

            rel:

              type: string

              description: A piece of information providing context for the link - e.g. self or accounts.

            href:

              type: string

              description: A fully qualified URL to the resource.

  errorModel:

    type: object

    properties:

      errors:

        type: array

        items:

          description: An array of error items containing error codes and descriptions. Note that the error descriptions will be normalised.

          properties:

            code:

              type: integer

              format: int32

              description: An error code - should be used in conjunction with the HTPP response code.

            description:

              type: string

              description: A short description of the error.

      _links:

        type: array

        items:

          properties:

            rel:

              type: string

              description: The relationship to the request e.g. self which contains the resource that was requested or {object name}, a link to a resource that is related to the requested resource

            href:

              type: string

              description: A link to the related resource. In an error scenario this is likely to be something such as a link to a support portal.

  _links:

    type: array

    items:

      properties:

        rel:

          type: string

          description: The relationship to the request e.g. self which contains the resource that was requested or {object name}, a link to a resource that is related to the requested resource

        href:

          type: string

          description: A link to the related resource

 

Page last updated: 19/12/2016