Quick Start: Add a New Path

Anatomy of a path

This topic looks at how paths are constructed and wired to response objects in the Swagger API specification file.

You've seen paths in previous Quick Start topics. The /hello path in the original Quick Start example looks like this:

  paths:
    /hello:
      # binds a127 app logic to a route
      x-swagger-router-controller: hello_world
      x-volos-authorizations: {}
      x-volos-apply: {}
      get:
        description: Returns 'Hello' to the caller
        # used as the method name of the controller
        operationId: hello
        parameters:
          - name: name
            in: query
            description: The name of the person to whom to say hello
            required: false
            type: string
        responses:
          "200":
            description: Success
            schema:
              # a pointer to a definition
              $ref: HelloWorldResponse
          # responses may fall through to errors
          default:
            description: Error
            schema:
              $ref: ErrorResponse

• First, open up the swagger editor by running: $ a127 project edit
• Under the paths object, add the new path as follows:

    paths:
      /weather:
        x-swagger-router-controller: weather
        x-volos-authorizations: {}
        x-volos-apply: {}
        get:
          description: "Returns current weather to the caller"
          operationId: getWeatherByCity
          produces:
            - application/json
          parameters:
            - name: city
              in: query
              description: "The city you want weather for in the form city,country"
              required: true
              type: string
          responses:
            "200":
              description: Success  

The parts of the path definition include:

• x-swagger-router-controller is a custom Apigee-127 extension to the Swagger model that maps a path to a controller file. For instance, /weather gets mapped to api/controller/weather.js.

• x-volos-authorizations can be used to apply schemes such as OAuth2.

• x-volos-apply can be used to apply volos quotas (Quickstart: Add Quotas) and caches (Quickstart: Add Caching).

• The other keys conform to the Swagger 2.0 specifications. The parameters is a YAML array that defines all the parameters required for the call. The responses object defines the response specifications for response codes.

Request and response models

The Swagger specification allows you to define both request and the response models (also called schemas). The path definition described in the previous section is an example of a request model.

Here's an example of an API that returns a relatively complex object. It is the Open Weather API that's used in the Apigee-127 samples project on GitHub.

The Open Weather API returns an object that looks like the following:

{
    "coord": {
        "lon": -77.58,
        "lat": 35.27
    },
    "sys": {
        "type": 1,
        "id": 1786,
        "message": 0.1057,
        "country": "United States of America",
        "sunrise": 1409913972,
        "sunset": 1409959883
    },
    "weather": [
        {
            "id": 500,
            "main": "Rain",
            "description": "light rain",
            "icon": "10n"
        },
        {
            "id": 211,
            "main": "Thunderstorm",
            "description": "thunderstorm",
            "icon": "11n"
        }
    ],
    "base": "cmc stations",
    "main": {
        "temp": 78.58,
        "pressure": 1021,
        "humidity": 88,
        "temp_min": 73.4,
        "temp_max": 82.4
    },
    "wind": {
        "speed": 5.62,
        "deg": 40
    },
    "clouds": {
        "all": 90
    },
    "dt": 1409876198,
    "id": 4474436,
    "name": "Kinston",
    "cod": 200
}

To wire the path to the schema, you add a responses to the path with a reference to the schema definition. In this example, we specify two responses, a 200 and an Error response. Note that you use $ref syntax to refer to each specific schema definition, listed in the #/definitions section (which we describe below).

Note: In this case, all other responses that are not 200 will be referred to the Error response schema.

    paths:
      /weather:
        ...      
        responses:
          "200":
            description: Success
            schema:
              $ref: WeatherResponse
          default:
            description: Error
            schema:
              $ref: ErrorResponse

Then in the #/definitions section of the Swagger document we define the WeatherResponse schemas that we referenced from the /paths section. Here is the schema that represents the JSON returned by the weather API (shown previously):

definitions:
  WeatherResponse:
    type: "object"
    properties: 
      base: 
        type: "string"
      clouds: 
        type: "object"
        properties: 
          all: 
            type: "number"
      cod: 
        type: "number"
      coord: 
        type: "object"
        properties: 
          lat: 
            type: "number"
          lon: 
            type: "number"
      dt: 
        type: "number"
      id: 
        type: "number"
      main: 
        type: "object"
        properties: 
          humidity: 
            type: "number"
          pressure: 
            type: "number"
          temp_max: 
            type: "number"
          temp_min: 
            type: "number"
          temp: 
            type: "number"
      name: 
        type: "string"
      sys: 
        type: "object"
        properties: 
          country: 
            type: "string"
          id: 
            type: "number"
          message: 
            type: "number"
          sunrise: 
            type: "number"
          sunset: 
            type: "number"
          type: 
            type: "number"
      weather: 
        type: "array"
        items: 
          type: "object"
          properties: 
            description: 
              type: "string"
            icon: 
              type: "string"
            id: 
              type: "number"
            main: 
              type: "string"
      wind: 
        type: "object"
        properties: 
          deg: 
            type: "number"
          speed: 
            type: "number"

Next steps

Now that you know have added a path, its time to implement the actual controller