In this document we would cover how users can implement, publish and share APIs with your customers and partners.
There are three overall steps to follow in order to setup a fully functional API architecture.
Step 1 is related to the process of implementing API in the Adeptia Solution (AS). Typically AS would be behind the firewall and this is the environment where users would design or promote their process flows into and have it available to the AS Gateway (DMZ).
This task also involves building complete set of JSON schemas, mappings, sources and targets that would be used for the different API operations such as AddEmployee, UpdateEmployee etc.
Process flows would represent the different API operations and each process needs to be published as a local end-point as explained further in the Step 1 below.
Step 2 is related to publishing of the local endpoints into a public facing API. The purpose of this step is to allow your clients to access the public API endpoint. The way this is achieved is to deploy another AS in the DMZ that would function as an API Gateway.
Step 3 is related how your customers be able to register, discover and consume these APIs. Purpose of using Adeptia Connect is to make it easy for all your customers to be able to send/receive data to your APIs through a simple, self-service integration wizard. Along with dashboards your customers would have full visibility to the API transactions, logs and data errors (if any).
First step is to setup a local end-point in your AS that is running behind your firewall. This part involves several sub-parts as explained below.
(Figure 1: Implement API in Adeptia Solution)
As part of this task, your team can develop process flows for the different types of API operations you would like to perform as part of the client request.
For example, suppose you have an operation called “Add Employee”. To implement this example, setup a process in AS that would take the particular JSON request from client related to new employee and map and process the information as part of the business use case. You may need to map the data to a database or internally call another web service to add the employee and then send a response back.
Here’s an example of a process flow:
Second step involves publishing and generating of end-point for your API. This task is accomplished via the Web Service Provider feature where we provide the service name, the method type and select the related process flow along with the schemas for request/response.
(Figure 3: Publishing the API locally in AS and generating local end-points)
After implementing and creating a WS Provider for that process flow, the local endpoints are listed in the Provider API Manage page as shown below.
(Figure 4: WS Provider - API repository in the AS)
In the API Gateway (AS on DMZ) a user can publish API, provide documentation and security token for authentication. Here are the steps to publish a public facing API.
(Figure 5: Implement API in Adeptia Solution)
For all the internal/local endpoints created in Step 1, user needs to create individual Web Service Consumer activities for each of those processes. Purpose of this task is to allow the main public facing API to call these endpoints based on the type of request.
(Figure 6: Web Service Consumer activities)
This process flow would take the client requests and relay the requests to the internal endpoints created in the AS that is behind the firewall. The purpose of this architecture is that the AS in DMZ would function as an API Gateway and would do the job of authenticating the incoming requests, determining which internal endpoints to call and then relaying back the response to the client.
This is also the place where user would provide the API documentation and the security token. And more importantly this process flow is published as an API that the clients would consume.
Here’s an example of the process flow in API Gateway.
As a prerequisite, user needs to define the security policy that can be selected when creating the Web Service Provider activity (see step 2D). Security policy consists of a security token that would be part of the request header sent by the client and will be used for request authentication at run-time.
(Figure 8: Creating a Security Policy for the API)
In this step we will use the Web Service Provider to publish our process flow as an API and generate a public facing endpoint.
(Figure 9: Publishing API by using the WS Provider screen - API Gateway)
After publishing the API, user can see the entire list of APIs in the WS Provider Manage page as shown here.
(Figure 10: APIs listed in the WS Provider Manage page - API Gateway)
Once the API is published, the next step is define the API documentation and this is accomplished by going to the particular API’s action icon and selecting “Edit Documentation’. This would open the API Documentation screen that would allow the user to enter the content specific to the API as shown here
(Figure 11: User provides full API documentation in this screen)
After providing the API documentation, user can view how the documentation would be shown to the clients by clicking on the “API Doc” under the Documentation column of the Manage page.
Here’s an example of the public view of the API documentation page.
(Figure 12: API documentation)
Now the next part in the API deployment process is how would your customers be able to discover and consume your API. And this is the part where Adeptia Connect plays a key role in making your APIs publicly available in a secure, cloud portal where your partners and clients can discover and consume your APIs.
(Figure 13: Share APIs in Adeptia Connect)
In the following we will go through the steps on how to make your APIs available to your customers.
In this step a user from your company would log into Adeptia Connect and specify the connection properties to access the API Gateway. Here’s a screenshot of the properties that are needed to connect to the API Gateway that is running on the DMZ.
(Figure 14: Configuring API Gateway in Adeptia Connect that would point to the API Gateway running on your DMZ)
In this step the user goes to My Shared Connection and creates Employee Connection and uses the public API as the target application as shown here.
(Figure 15: Creating an API shared connection in Adeptia Connect)
This is the final step of deploying your APIs into the Adeptia Connect. Now your customers can login to Adeptia Connect and explore all the connections that are available from your company and would be able to consume these connections in minutes.
(Figure 16: List of Shared Connections that your partners and customers can explore and consume)