SAP API Management – do you speak OpenAPI (aka. Swagger)?

When I was a kid, at school, my English lesson-book was called “Do you speak English?” (featuring Patty and Sam!). Already then, we all knew that English was the language the whole world was talking, easing communication around the globe.
Wouldn’t it be great that API users, API developers and API platforms talk the same language, to agree on what they do? Swagger, now called OpenAPI, is a widely adopted markup language, that does a very good job at describing APIs. In case you talk RAML, you’ll find a lot of RAML-to-Swagger tools so you can translate your API specifications.

Why OpenAPI?
In the world of APIs, the description of APIs is essential: there is no such thing as “Enterprise Repository”, like in the SOA world. Therefore, the description (including documentation) of your APIs has to be excellent.
The description of APIs actually covers three aspects:
– documentation: a well written API description can be read and understood by any developer wanting to use the API. It can also be integrated into various UIs eg. Portals, to be published.
– implementation: the API description is the guideline for the developer actually implementing the API, who then exactly knows what his API should do,
– contract between developer and API provider: even if the API is not yet implemented, both the API user (for instance developer) and the API developer have agreed on a common model, and can start working in parallel. If the contract changes, both parties are involved and should agree on it.

OpenAPI in SAP API Management
With the latest August release of SAP API Management in the Hana Cloud Platform, we introduced the “API Designer” feature.
This feature let’s you create an API Proxy based on an existing OpenAPI file. This is pretty useful in case you have already implemented your API, and you want to expose it to your partners or developers in a secured and tailored way over HCP API Management.
In case you are starting with APIs, and you need to implement them first, it’s also a very good idea to follow the “design first” approach. This means that you first define what your API will look like, and what it will do, once finished.

This blog will guide you through an example of using the API Designer of HCP.

Pre-requisites
To follow on this example, it is good that you have some basic understanding of the API Management Service of the HCP. This service also needs to be enabled in your HCP tenant.

Step 1
First of all, we need an API description. I have written a simple Financial Services API description, that allows the API user to get and create branches of a Bank.

swagger: '2.0'
info:
  version: '1'
  title: FinServDemo API
  x-targetEndpoint: 'https://trial.apim1.hanatrial.ondemand.com'
host: 'trial.apim1.hanatrial.ondemand.com:443'
basePath: //v1/FinServDemoAPI
schemes:
  - http
  - https
consumes:
  - application/json
produces:
  - application/json
paths:
  /branches:
    x-swagger-router-controller: finServ_demo
    get:
      parameters:
        - name: apikey
          description: The API key provided by the Developer Portal
          in: query
          type: string
          required: true
        - name: postalCode
          description: The postal code around which to search for branches
          in: query
          type: string
          required: false
        - name: radius
          description: The radius (in KM) in which to search for branches
          in: query
          type: string
          required: false
      description: >
        Returns all branches


        This method returns all branches of the Bank located within the radius
        of the postal code.


        Example of use:


        /branches?apikey=123&postalCode=65123&radius=25
      operationId: branches
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/branchesResponse'
        default:
          description: Error
          schema:
            $ref: '#/definitions/ErrorResponse'
    post:
      parameters:
        - name: apikey
          description: The API key provided by the Developer Portal
          in: query
          type: string
          required: true
        - name: branchData
          description: The branch definition in JSON
          in: body
          schema:
            type: string
            example:
              name: Branch1
              phoneNumber: +49 123 456 789
              email: Branch1@bank.com
              address: Hauptstrasse 1
              69190 Walldorf: null
              location: 49.303235;-8.6428548
          required: true
      description: Creates a branch. The branch UUID is delivered as part of the response.
      operationId: createBranch
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/branchesResponse'
        default:
          description: Error
          schema:
            $ref: '#/definitions/ErrorResponse'
  '/branches/{branchUUID}':
    x-swagger-router-controller: finServ_demo
    get:
      parameters:
        - name: apikey
          in: query
          type: string
          required: true
        - name: branchUUID
          in: path
          type: string
          required: true
      description: Returns the information of the branch identified by the UUID
      operationId: branch
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/branchesResponse'
        default:
          description: Error
          schema:
            $ref: '#/definitions/ErrorResponse'
definitions:
  branchesResponse:
    properties:
      uuid:
        type: string
        description: Unique identifier of the branch
      name:
        type: string
        description: Name of the branch
      phoneNumber:
        type: string
        description: Phone number of the branch
      email:
        type: string
        description: Email of the branch
      address:
        type: string
        description: 'Full address including street, number, ZIP code and city name'
      location:
        type: string
        description: Latitude and Longitude coordinates
  ErrorResponse:
    required:
      - message
    properties:
      message:
        type: string

Note that the description is pretty readable already. You can sepnd some time reviewing the description to get an understanding of it’s contents. Basically, I am describing 2 resources:
– branches: used to get all branches, or only those is the specified radius (optional)
– branches/{uuid}: used to return only one specific branch identified by its unique identifier

Step 2
Now that we have our API description defined, it is time to create a proxy based on that description.

Log in to your Hana Cloud Platform Cockpit.
Open the API Management Service.
Click on the third icon to access the API proxies.

Click on the new button called “Create in API Designer”.

The API Designer opens, with a predefined skeleton of an API description.

Because we already have the description of the API, which should be the case most of the time, we will not start editing the description.
Simply replace the complete YAML on the left side with the description I posted above.

Notice that the errors on the right have disappeared because the OpenAPI description is complete and correct.
Now you can navigate the OpenAPI file on the left, and see you changes being reflected immediately on the right. If you make any error, the error is highlighted in real-time (be careful about indentation in your OpenAPI description for instance).

In order to create the API Proxy from the API Designer, select “Save” in the “File” menu:

You can now specify the name of your API Proxy that will be created in SAP API Management. Name it “FinServDemoAPI” for instance, hit the “Save” button and navigate back to the API Proxy list.

Step 3
In the API Management Portal, you can see that the “FinServDemoAPI” Proxy has been created for you.

Click on the name of the API Proxy to review its details.

As you can see, the API Proxy has been set accordingly to your specification: URL, resources and documentation have been imported to your proxy!

Conclusion
Although the API Designer is still “work-in-progress”, it allows you to simply re-use your OpenAPI description, in order to quickly generate a REST API Proxy.

For comments or feedback, feel free to reach out directly to me, or post a comment to this blog!