What is API management?

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.

Examples of API management systems include these and others:

  • Azure API Management
  • AWS API Gateway
  • Mulesoft Anypoint
  • Apigee
  • Kong
  • Boomi

API management and other proxy approaches

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:

externalhost:443/server/rest/services/ » internalhost:6443/arcgis/rest/services/

API management usually involves specification of individual API URI paths and HTTP methods (i.e. a POST to /routes/extract and a PATCH to /routes/), 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.

API management also usually includes an array of other processing options, that either manipulate request contents (adjusting a path, adding 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).

API management and ArcGIS

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:

  • API management generally works best as an architectural pattern with stand-alone ArcGIS Server deployments. Handling the token exchange and validation required for a federated server as part of an ArcGIS Enterprise deployment is significantly more complex and would require either advanced ArcGIS configuration or API management configuration to handle the variety of authentication requests and endpoints.
  • ArcGIS REST services are usually anonymously accessed by the API management system, and requests from the API management “service” are sent to the ArcGIS backend without further interruption. While ArcGIS supports many authentication patterns, from built-in usernames and passwords to SAML and OIDC, an API management pattern frequently assumes that the backend API is anonymously accessible to request originating from the API management service. This means that ArcGIS services should usually be “shared to Everyone” but limited through a network design or firewall to only allow requests from the API Management service or instance.
  • API management should generally be used to expose specific services or endpoints, not entire ArcGIS Server sites. If your goal is to expose an entire site, a traditional reverse proxy is usually a better solution that will be more compatible with workflows.
  • ArcGIS generally provides more verbose REST APIs, which means the API management service must support either flexible wildcard patterns or forward specific paths only. This is especially relevant if the goal is to expose the service to ArcGIS client software, which is designed to expect a fully available API (where all methods and resources can be accessed).

For example:

  • Forwarding this request is sufficient to get details about a specific service:
    • /arcgis/rest/services/ServiceName/MapServer
  • However, if you want to support map service functionality and feature layer functionality, you must additionally forward these types of requests:
    • /arcgis/rest/services/ServiceName/MapServer/exportImage
    • /arcgis/rest/services/ServiceName/MapServer/0/query
    • /arcgis/rest/services/ServiceName/MapServer/1/query

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.