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).
Step 1: Implementing API in Adeptia (AS behind firewall)
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)
1A. Design Process Flow
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:
- Takes the incoming request in JSON to Add Employee
- Validates and maps the data to the database
- Generate a response
- Send the response back to the client
1B. Generating local end-points for your API operations
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)
Step 2: Publishing API in Adeptia API Gateway (AS installed in DMZ)
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)
2A. Create Web Service Consumer activities that point to internal endpoints
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)
2B. Create a process flow that would call the internal endpoints
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.
2C. Create Security token for your API
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)
2D. Publish API in API Gateway
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)
2E. Creating documentation for your API
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)
Step 3: Sharing your APIs with your customers & partners (Adeptia Connect)
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.
3A. Configuring the API Gateway properties in Adeptia Connect
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)
3B. User makes the API available to partner network by creating a Shared Connection
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)