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!
Hello Sven,
many thanks for your blog.
This has definitely helped in creating a new API proxy.One thing which I want to know is whether we can add multiple hosts in this.
Is there any possibility for that??
Hello Suraj,
glad to hear it helped!
As far as I know, OpenAPI, fka. Swagger only supports one host entry.
However, if you are talking about host being a backend from within your API Proxy, then yes: you can define routing rules based on conditions and send your request to one host or to another at runtime. This routing is typically done in an API management layer, and not defined in the Swagger file.
I hope this helps!
Cheers,
Sven
Hi Sven - Does the API Management Swagger 2.0 supports open API 3.0 specifications.
As Swagger allows to generate the API Documentation, I used swagger and downloaded the Open API specification and imported into API Designer, but designer throws an error.
So my basic question is does Open API 3.0 is supported?
Thanks & Regards
Rajesh Pasupula
Hi Rajesh,
as for now, only the API Business Hub supports Open API 3.0. For the API Designer of the API Management Service, Open API 3.0 is on the roadmap.
Cheers,
Sven
Hi Sven,
Thank you so much for the blog!
Can API designer be used for creating SOAP API proxy?
Thanks in advance,
Neeharika