In part 1 of this series, we looked at three things:
- The origins of why an API Management solution is needed in the first place
- How SAP has chosen to implement their solution
- The 4 basic data objects that act as the building blocks from which an API is exposed to the outside world.
In this document, we will build on that knowledge and look in overview at the tools used to create and maintain these data objects.
In order to help us keep track of where we are in the big scheme of things, I will use the diagram on the right as a roadmap, in which we will start at the bottom, and work our way up using first the API Portal for proxy development, then switch to the API Portal for proxy consumption.
Creating a System
At this point in the development process, we are acting as a Proxy Developer, therefore we must use the API Portal.
From the hamburger menu in the top left, select the Configure option.
In the bottom right corner, there is a Create menu. Click here to create your new System.
All we’re doing here is creating a logical name by which a backend system can be identified within the API Management framework.
Another important point to understand here is that perhaps surprisingly, the creation of a System is not mandatory.
If you are wanting to access a backend system that exposes its functionality through OData services, this it is useful to create a System.
The creation of Systems is also useful for reusability. Once you have created a System, you can access any service from that backend system using nothing more than the System name created here, and the relative path to the particular service of interest.
When creating a system, you should supply three different blocks of information:
- The connection information to the actual server. This includes the host name, port number and an optional path prefix. For instance, if you are creating a System to represent an ABAP backend, then you will probably want to add the path prefix of “/sap/opu/odata” in order to restrict access to only the resources exposed from this path.
- Authentication. If supplied, the hard coded userid and password will be used by the API Portal’s design time tools when you come to consume services from this backend system.
- Lastly, the Catalog URL (if supplied), will allow the API Management design-time tools to invoke the special CATALOGSERVICE OData service. This is a special OData service provided as standard with all ABAP systems, and its purpose is to list all the OData services exposed by this ABAP system. Within this service is an OData collection called ServiceCollection that lists all the available OData services.
As was mentioned above, this configuration is optional; however, if you do not supply it, then when we arrive at the next step of creating an API Proxy that points to an OData service, the design time tools will not be able to query the backend system and present you will a list of available services. In this case, you will need to know the full path name to the OData service yourself.
Creating an API Proxy
We now come to the part where all the work takes place. Creating API Proxies is the heart of API Management, and this is where you will spend the bulk of your time.
From the hamburger menu in the top left, select Manage.
A new API Proxy is created by clicking on the Create menu in the bottom right corner.
At this point, you have the option of either creating an API from scratch, or importing one.
Should you wish to import an API, you must first have exported the API from some other SAP API Management system. (An exported API consists of a ZIP file within which the various parts of the API have been dumped as XML files).
Assuming you want to create an API Proxy from scratch, you will need to provide all the initial details yourself.
Pointing to the Backend System
As was mentioned above, when you create an API Proxy, you can specify that you want to consume a service exposed by some backend system for which you have already created a System. The name of the System is then chosen from the drop-down list called “API Provider”. However, this is not the only way of doing it. Alternatively, you can leave the API Provider entry set to NONE, and then enter the full URL to the service. This second approach is sometimes used if you wish to consume something like a public Web Service (SOAP).
Either way, using the information supplied in both the API Provider and URL fields, the tool for creating the API must be able to fully identify the required service.
Also note that if you select a System from the API Provider drop-down list, then a new button will appear to the right of the drop-down called “Discover”.
Remember what was mentioned above about the Catalog URL? Well, here’s where that configuration is used. If you supplied a Catalog URL when you created the System (or API Provider), then you will now be able to click on the Discover button and see a list of all the OData services available in that System.
Alternatively, if you did not supply a Catalog URL, then the Discover button will not do anything.
It’s important to understand that this “Discover” feature is designed only to work against backend systems that provide a specific CatalogService OData service.
Naming the API Proxy
Once the URL of the backend service has been defined, you can now give the API proxy a name and a description.
The API Base Path field is important to understand. This field holds the URL used when the API Proxy is consumed by the external user.
This URL must be unique across all the API Proxies you create. That said, if you wish to create two different API Proxies that both point to the same backend service, then this is perfectly possible as long as you use two different values for the API Base Path.
The point at which we now find ourselves is that although we have created an API Proxy, this proxy is quite passive, providing no additional functionality when invoked. Nonetheless, we will stop here in the discussion of creating API Proxies for two reasons: the first being that this current document is just an overview of the available API Management tools, and the second being that the development of an API Proxy is large and detailed topic that must be discussed individually. Such as discussion will follow in due course.
Creating a Product
Now that we have an API Proxy (albeit one that adds no value), we can now add this Proxy to Product in order to expose it to the outside world.
As was said in the first document, the Product is the unit of API Exposure. In other words, if you want your Proxy to be exposed to the outside world, you must first add it to this data object called a Product. Although there are no hard and fast rules here, it is typical to create a Product that contains all the API Proxies related to one type of business task or process.
By selecting “Product” from the tab menu in the “Manage” screen, you can add or remove API Proxies from the Product.
Remember that a Product can contain many API Proxies, and that the same API Proxy can belong to many Products.
Since we have added the API Proxy to the Product, this API Proxy is now visible to the outside world. We have now finished all the tasks required of an API Proxy developer, and we must now change hats and look at these proxies from the perspective of a frontend app developer.
Discovering the Available API Proxies
Now that we have switched personas from an API Proxy Developer to a frontend app developer, we are no longer interested so much in the internal workings of the API Proxy, but rather being able to consume that proxy from within the larger scope of an external business application.
In addition to switching personas, we must also switch API Management tools. Up till now, we have done all the work in the API Portal, but now we need to switch to the Dev Portal. Return to the API Management service via your HCP account cockpit and select “SAP API Management Dev Portal”.
You are now taken to a screen that looks similar to the API Portal, but here you have no ability to create or change API Proxies.
From the hamburger menu, select the Discover option and you will now see a list of all the available Products. By selecting a Product, you can see a list of all the API Proxies it contains, which in turn, takes you to a test tool for each service exposed by the API Proxy.
Consuming API Proxies
When you have found the Product or Products you want, select the Consume option from the hamburger menu. Now by clicking on the Create option in the bottom right of the screen, you can create your own Application.
Remember that the term “Application” is not being used in the normal sense of a unit of software with which a user interacts in order to perform some business task. Instead here, the term Application means the set of Products to which you have subscribed for the purposes of building some client application. So, in one sense the API Management term “Application” does potentially refer to the unit of business software more traditionally referred to as an application, but even if this is true, the reference is only indirect.
Once you have added as many products to your Application as you require and saved it, you will be given an Application Key. This is a randomly generated string that serves to uniquely identify your specific usage of the selected Products.
When you create an Application, you are creating a unit of API Subscription. This unit of subscription is then identified by its Application Key, and this very must typically be supplied each time a call to an API Proxy is made.
In the next document, we will take a look at creating the necessary HCP Destinations in order for you to be able to consume API Management Proxies using the SAP Web IDE.