Administration APIs

API Gateway Administration

API Gateway provides the following REST API and the resources to manage API Gateway configuration:

For details on sample payloads, import Postman collection from the following link in Postman client: https://github.com/SoftwareAG/webmethods-api-gateway/blob/master/apigatewayservices/postmancollections/apis/administration-service/AdministrationService.json.

Alias Management

API Gateway provides the capability to create aliases, retrieve alias information, update alias properties as required, and delete the existing aliases using a REST API.

API Gateway provides the following REST API and the resources to manage aliases:

For details on sample payloads, import Postman collection from the following link in Postman client: https://github.com/SoftwareAG/webmethods-api-gateway/blob/master/apigatewayservices/postmancollections/apis/alias-management/AliasManagement.json.

Application Management

API Gateway provides the capability to create applications, retrieve application information, update application properties as required, and delete the existing applications using a REST API. You can use this REST API to register APIs to the application, modify details of the registered APIs for the application, and unregister APIs from the application.

API Gateway provides the following REST API and the resources to manage applications:

For details on sample payloads, import Postman collection from the following link in Postman client: https://github.com/SoftwareAG/webmethods-api-gateway/blob/master/apigatewayservices/postmancollections/apis/application-management/ApplicationManagement.json.

API Gateway Archive

You can import already exported archives of APIs, global policies, and other related assets and re-create them in API Gateway. Each artifact in an archive is associated with a universally unique identifier (UUID) across all API Gateway installations. When importing an archive, the UUID helps in determining whether the corresponding artifact is already available in API Gateway. In such a situation, you can specify whether to overwrite an already existing artifact during the import process.

API Gateway provides the following REST API and the resources to export and import an archive:

For details on sample payloads, import Postman collection from the following link in Postman client: https://github.com/SoftwareAG/webmethods-api-gateway/blob/master/apigatewayservices/postmancollections/apis/archive-service/ArchiveService.json.

API Gateway Availability

API Gateway provides the capability to monitor the health of API Gateway and report the overall health of API Gateway. Each health check request displays a status field as the first entry. The status can have the values green, yellow or red describing the overall status of the components to check. This means that when any of the components signals a problem, then the status is set to red.

API Gateway provides the following REST API and the resources to monitor the health of API Gateway:

• GET /gateway/availability/admin: Retrieves the availability and health status of the API Gateway administration service (UI, Dashboards, Admin REST API).
• GET /gateway/availability/engine: Retrieves the availability and health status of the Gateway policy enforcement engine (ElasticSearch cluster, IS and TerraCotta).
• GET /gateway/availability/externalServices: Retrieves the availability of external services accessed by API Gateway.
• GET /gateway/availability/all: Retrieves the availability of the administration service of the policy enforcement engine and of the external services accessed by API Gateway.

You can use the existing health check request GET/rest/apigateway/health, without any authentication being set, to retrieve the health of API Gateway. This returns a HTTP 200 response without additional data.

Document Management

API Gateway provides the capability to store and manage the documents associated with an API.

API Gateway provides the following REST API and the resources to manage the documents associated with APIs:

For details on sample payloads, import Postman collection from the following link in Postman client: https://github.com/SoftwareAG/webmethods-api-gateway/blob/master/apigatewayservices/postmancollections/apis/document-mangement-service/DocumentManagementService.json.

Internal Service

API Gateway provides internal APIs that work on identified applications that are identified based on identifiers such as API Key, OAuth token, IP address and so on.

API Gateway provides the following REST API and the resources to manage application identification:

• POST/{apigateway}/security/getJsonWebToken: Generates JSON Web token with custom claims supplied in the request.
• POST/{apigateway}/security/exchangeIDToken: Generate an access token for the given ID Token.

Policy Management

API Gateway provides the capability to retrieve API Gateway policy related data such as policies, parameters, policy stages, policy templates, binding assertion, token assertion and service result cache. You can use this REST API to create, update or delete policies.

API Gateway provides the following REST API and the resources to manage policies:

For details on sample payloads, import Postman collection from the following link in Postman client: https://github.com/SoftwareAG/webmethods-api-gateway/blob/master/apigatewayservices/postmancollections/apis/policy-management/PolicyManagement.json.

Promotion Management

API Gateway provides supports staging and promotion of assets. Staging and promotion allows you to promote all the assets across different stages.

API Gateway provides the following REST API and the resources to manage staging and promotion:

For details on sample payloads, import Postman collection from the following link in Postman client: https://github.com/SoftwareAG/webmethods-api-gateway/blob/master/apigatewayservices/postmancollections/apis/promotion-management/PromotionManagement.json.

Public Services

This API allows you to fetch a JWT from API Gateway and also fetch JSON Web key URI of API Gateway.

API Gateway provides the following REST API and the resources to manage public services:

• GET/rest/pub/apigateway/jwt/getJsonWebToken: Retrieves JWT from API Gateway. To obtain the JWT from API Gateway the client has to pass the basic authentication credentials.
• GET/rest/pub/apigateway/jwt/certs: Retrieves all the public keys of API Gateway, which can be used to validate the JWT generated by API Gateway.

API Gateway Search

The API Gateway search API allows you to execute a search query in API Gateway and retrieve search results that match the search query.

Remember: When your search involves a large number of records, the process consumes a considerable memory space from the server, which in turn affects other business transactions. Hence, Software AG recommends that you perform large search operations when you expect lesser business transactions so that the regular business is not affected.

API Gateway provides the following REST API resources:

• POST/rest/apigateway/search: Executes a search query in API Gateway and returns the results that match your query. You can perform search across the different objects such as APIs, Applications, Aliases, Assertions, Policies, Administration Settings, Policy properties, Packages, Plans, Subscriptions, Users, User groups, Transactional events, Lifecycle events, Policy violation events, Monitor events, Error events, Threat protection events, and Performance metrics.

To perform a search operation, specify the following in your REST request:

REST Request Section	Description
Types	Objects for which you want to perform the search operation. You can specify one or more of the listed objects. Note: When you specify Users and User Groups in the Types section to return the list of users and user groups from Integration Server respectively, you need not specify any search criteria.
Scope	Search Criteria. You must specify your search attribute and a keyword (value of the attribute) or one of the following as your search criteria: Time range - to retrieve results for a date range (from and to values), from a specified date to current date, till a specified date, or since the given amount of time (seconds, minutes, hours, days, weeks, months, quarters, or years). Value range - to retrieve results for a integer value range (from and to values), from a given value to the maximum value, and from 0 to the given value. You can specify multiple attributes in this section. Note: The search operation is performed based on the search criteria specified in this section for all objects specified in the Types section.
Condition	One of the following: and - to return results that match all search criteria. or - to return results that match any of the given criteria.
Fields	Fields to be returned in the response. You can specify only the required fields, instead of viewing all fields in your response. That is, if you want to view only the API Names and Versions that match your search criteria, you can specify apiName and apiVersion in this section of your REST request.

• POST/rest/apigateway/search/_count: Retrieves the total number of records for the specified scope and types.

To retrieve the count of records, you can specify the required types and scope similar to the /search query. If you do not specify any search criteria in the Scope section, then the query returns total number of assets for the objects specified in the Types section.

• POST/rest/apigateway/search/_aggregations: Executes a search query and groups the results for the specified scope and types.

To perform an aggregations search, specify the following in your REST request:

REST Request Section	Description
Types	Objects for which you want to perform the search operation. You can specify one or more of the listed objects.
Scope	Search Criteria. You must specify your search attribute and a keyword (value of the attribute) or one of the following as your search criteria: Time range - to retrieve results for a date range (from and to values), from a specified date to current date, till a specified date, or since the given amount of time (seconds, minutes, hours, days, weeks, months, quarters, or years). Value range - to retrieve results for a integer value range (from and to values), from a given value to the maximum value, and from 0 to the given value.
Condition	One of the following: and - to return results that match all search criteria. or - to return results that match any of the given criteria.
Aggregations	Values for the following: Name - Specify a name used to group the required results. For example, you can specify Info by API, if you are grouping the results by APIs. Type - One of the following: group - to group the results based on the given fields. timeseries - to group results based on a given interval value. The interval can be seconds, minutes, hours, days, weeks, months, quarters, or years. metrics - to find the average, minimum, maximum and sum of given fields. Fields - Fields to be considered for the aggregation. If the type is group and there are multiple fields, separate the field names with commas.

Note

The number of transactions returned for a search is based on the value specified in the defaultSearchSize extended setting. If your search result exceeds the value of this setting, then you can navigate through your search results by specifying the range of records that you want to view. For example, the value specified in the defaultSearchSize setting is 1000 and the count of your search result is 5000, then only the first 1000 records are displayed. To view the consequent records, you can specify the number of the record from which you want to view, and the number of records that must be displayed. That is, to view the records from 1001 to 2000, you can specify the range as follows:

POST http://localhost:5555/rest/apigateway/search

{ 
   "types": [
        "TRANSACTION_EVENTS"    ],
    "scope": [
        {  "attributeName": "responseCode",
            "keyword": "304"        
								},     
						],
    "from": "1001"
    “size”: “1000”
}

For details on sample payloads, import Postman collection from the following link in Postman client: https://github.com/SoftwareAG/webmethods-api-gateway/blob/master/apigatewayservices/postmancollections/apis/search-service/SearchService.json.

Service Management

API Gateway provides the capability to retrieve and manage all APIs in API Gateway and the related information such as applications associated, scopes, versions and so on.

API Gateway provides the following REST API and the resources to manage services:

For details on sample payloads, import Postman collection from the following link in Postman client: https://github.com/SoftwareAG/webmethods-api-gateway/blob/master/apigatewayservices/postmancollections/apis/service-management/ServiceManagement.json.

Transaction Data

API Gateway provides the capability to to query the API transactions. API Transactions are generated (as events) every time an API invocation happens. API Transactions may contain the details about the invocation such as request and response headers, request and response payloads, consumer applications and so on. API Provider may choose to store these events to one or more destinations by using Log Invocation Policy. API Gateway provides different destination options to the API Provider (like API Gateway’s own data store, relational databases, Elasticsearch, and so on) where the events can be stored. By default, API Gateway is chosen as a storage destination for these events. This REST API queries for the transactions data only from the API Gateway’s default datastore. There are multiple use cases where you can use this transactions data. For instance, you can integrate this API with your billing system wherein this transactional data can be used to compute the usage history of your API for different consumers for monetization usecases. In other scenarios, the data extracted from this service can be used for custom report generation.

API Gateway provides the following REST API and the resources to retrieve the transaction events data:

For details on sample payloads, import Postman collection from the following link in Postman client: https://github.com/SoftwareAG/webmethods-api-gateway/blob/master/apigatewayservices/postmancollections/apis/transaction-data-service/TransactionDataService.json.

User Management

API Gateway provides the capability to manage Users, Groups and Access profiles in API Gateway.

API Gateway provides the following REST API and the resources to retrieve the User ACL list:

For details on sample payloads, import Postman collection from the following link in Postman client: https://github.com/SoftwareAG/webmethods-api-gateway/blob/master/apigatewayservices/postmancollections/apis/user-management/UserManagement.json.

Subscription Management

You can manage subscriptions from the REST API provided by API Gateway. This API allows you to create application, view applications, get the application details for a specific package and plan, and so on. Alternatively, you can also use Developer Portal to manage subscriptions. To use the subscription APIs, you must have the Manage application permission.

API Gateway provides the following REST API and the resources to manage subscriptions:

• POST/rest/apigateway/subscriptions: Creates a subscription and generates an audit log event. The newly generated event is returned. If the approval is enabled, the application details are returned without the API key. Once the request is approved, user can get subscription details and can view the access key. If the approval is not enabled, then the response contains all the application details, except for the API key. The API key is masked and only the requester can view it.


• PUT/rest/apigateway/subscriptions/{applicationId}: Updates the subscription details. You can change the package and plan of a subscription. This API can be used only to update the package and plan details.


• GET/rest/apigateway/subscriptions: Retrieves the subscriptions created as applications. The API key is masked for all the subscriptions.


• GET/rest/apigateway/subscriptions/{applicationId}: Retrieves the details of a specific application. You must provide the application ID as input parameter.


• GET/rest/apigateway/subscriptions?packageId={packageId}&planId={planId}: Retrieves the application details for a specific combination of package and plan.


• GET/rest/apigateway/subscriptions/usage: Retrieves the subscription usage details of all the subscriptions for the current cycle of only the existing subscriptions.


• GET/rest/apigateway/subscriptions/{applicationId}/usage: Retrieves the usage details for a specific application. You must provide the application ID of the required application, as an parameter.
  
  GET/rest/apigateway/subscriptions/usage?name={applicationName}& package={packageName}&plan={planName}&from={startingIndexOfSearchResult}& size={numberOfRecordsToFetch}&count={boolean}:
  
  Retrieves the usage details for a specific application's package and plan. The package name, application name, and plan name are given as input parameters. The from, size, and, count parameters are optional. If you provide the from and sum parameters, the values specified in the from and number of records, specified in the size are fetched. If you set the count parameter to true, the API returns number of records for specified query parameter.


• DELETE/rest/apigateway/subscriptions/{applicationId}: Deletes an application. You must provide the application ID of the application to be deleted.

Backward compatibility support for REST APIs

All the REST APIs in API Gateway are backward compatible. The backward compatibility handles payload transformation from the previous version to the current version of API Gateway. If you want to use version specific payload then use the corresponding endpoint. For example, if you want to use the 10.1 payload to create an asset, then you have to use http://hostname/rest/apigateway/v101/asset

With the backward compatibility support, API Gateway exposes the following REST end points with the version number mentioned.

• http://hostname/rest/apigateway/v101/assetsspecificURI

Use this URI if you want to access the latest API Gateway with 10.1 version specific request and response.

The following policies have conflicting behaviour compared to earlier versions:


• In 10.1 invokeESB templateKey is used to create Invoke webMethods IS policy that can be used for both request and response transformation stage. From 10.2 version, the invokeESB templateKey is changed to requestInvokeESB and responseInvokeESB for request and response transformation stage respectively. So when you send a payload with older version \(10.1\), it is not possible to create the correct policy in latest version. To solve this, you have to update the payload, and send the appropriate templateKey in 10.1 payload. For example if you are creating invoke webMethods IS policy for request transformation, then you have to specify requestInvokeESB templateKey instead of invokeESB templateKey.


• In 10.1 xsltTransformation is used to create XSLT Transformation policy that can be used for both request and response transformation stage. From 10.2 version, the xsltTransformation templateKey is changed to requestTransformation and responseTransformation for request and response transformation stage respectively.To solve this, you have to update the payload, and send the appropriate templateKey in 10.1 payload. For example if you are creating XSLT Transformation policy for request transformation, then you have to specify requestTransformation templateKey instead of xsltTransformation templateKey.
• http://hostname/rest/apigateway/v102/assetsspecificURI

Use this URI if you want to access the latest API Gateway with 10.2 version specific request and response.

• http://hostname/rest/apigateway/v103/assetsspecificURI

Use this URI if you want to access the latest API Gateway with 10.3 version specific request and response.

• http://hostname/rest/apigateway/assetsspecificURI

When there is no version mentioned, the URI, by default, accesses the latest version specific request and response.