In an architectural or system design context, API management commonly refers a configurable, highly capable reverse proxy that is used to manage access from clients (external, internal, or otherwise) to an API, endpoint, or method. Commonly used with RESTful APIs but not exclusively, API management provides a layer of request management and protection so that an incoming request can be verified, inspected, changed, and acted upon, and the response that comes back from backend system can be further modified or acted upon. Some organizations may use an enterprise service bus to achieve similar goals. An enterprise service bus is a flexibly-defined term for a class of technologies which include additional implications related to that component but can benefit from the same set of recommendations for API management services.
Examples of API management systems include these and others:
API management behavior is different from a traditional reverse proxy, which usually forwards an entire pattern of HTTP traffic to a backend server. For example:
<external-host>:443/server/rest/services/* » <internal-host>>:6443/arcgis/rest/services/*
API management often involves the selection of individual API URI paths and HTTP methods (i.e. a POST to /routes/extract and a PATCH to /routes/<routeid>), which means that each individual method or pattern must be defined, but also that each pattern can have different rules, behaviors and backend listeners or services. This is often used in constructing new APIs or systems, where an existing set of web services does not exist, or in enabling a microservices-style architecture where different backend components or systems are responsible for servicing separate API requests. In some cases, API management may use a backend API definition such as an OpenAPI specification to create many frontend endpoints or methods.
API management also usually includes an array of other processing options that either manipulate request contents (adjusting or rewriting a path, adding or modifying a header, changing the destination based on POST body content), apply some filtering to the request (rate limiting, blocking certain IP ranges, requiring API keys), or operating on the response (obfuscating server names, removing response headers, adding a fingerprint or identifier). These operations are defined in the API management layer and operate on each request as it is submitted and a response is created.
All of these patterns generally apply to enterprise service bus technologies as well, with a few differences. ESBs tend to be more focused on synchronous message delivery, where a change in one part of the system (a new record is added, an update is made) triggers a push of this change to the ESB, which then transforms and pushes the message to other systems to keep them in sync. In a sense, API Management is more of a query and poll methodology, where ESBs more often introduce strong message delivery commitments, pub-sub patterns or other similar approaches.
API management can be used in many different patterns with ArcGIS. Generally, API management is most applicable to use cases where it is deployed “in front” of ArcGIS Server-based services, such as map, feature, or geoprocessing services, in scenarios where those services need to be exposed either to another enterprise system or to a developer or end client using a customized application. A few key considerations for working with API management include:
For example:
/arcgis/rest/services/ServiceName/MapServer/arcgis/rest/services/ServiceName/MapServer/exportImage/arcgis/rest/services/ServiceName/MapServer/0/query/arcgis/rest/services/ServiceName/MapServer/1/queryAPI Management is an increasingly popular way to provide integration options between enterprise systems. Many organizations invest in or create policies to ensure that all internal transactions are brokered by an API management system, or may require use of API management to create externally-accessible services. In the context of system integration, best practices include:
API management does not by definition include an authentication layer, but many organizations wish to apply authentication to their API management endpoints, for purposes of user validation and authorization management. Common API management authentication methods include the use of an API or subscription key as well as integration with OAuth-based authentication methods to an existing Identity Provider (IdP). Each of these patterns can create some challenges with ArcGIS integration workflows.
Be aware that API management-based client authentication methods may not be compatible with standard ArcGIS clients. For example, if header-based authentication is required by the API Management system, either using a service-specific header or a Bearer Authorization header, standard ArcGIS clients will not be able to add that header dynamically to requests to support accessing that service. Similarly, API keys might be a common authentication layer added through an API management interface, but application developers need to be aware of this requirement and have the ability to add it to requests in order to integrate these services into an application. Various ArcGIS SDKs and service registration patterns can support this kind of subscription key or API key authentication pattern but should be carefully tested before assuming an authentication pattern is suitable.
OAuth-based authentication to API management presents other challenges. When developing a custom application using a supported SDK, it may be relatively simple to provide an initial redirect to the OAuth service, return a token or code, and use that token to append to further requests in that session. However, when using ArcGIS off-the-shelf application, this configuration is much harder to use successfully as these clients expect to directly access ArcGIS geo-services, without additional authentication steps that are unmanaged by ArcGIS.
Generally, the use of API or subscription keys provides the most successful integration path in this context, with the following recommendations: