Overview of service interceptors

What are service interceptors?

Service interceptors are an extensibility pattern in ArcGIS Enterprise that allows developers to inspect and modify existing service requests and responses at runtime. These lightweight and customizable components can intercept network traffic from any service published to ArcGIS Enterprise, regardless of its service type. They execute custom business logic and modify the behavior of services by overriding resources or operations in a manner that is seamless to clients, such as ArcGIS Pro and Map Viewer, among others. Currently, service interceptors are only capable of intercepting REST-based services.

By providing robust hooks into the request and response lifecycle, service interceptors enable the execution of custom business logic, such as logging, authorization, validation, or data enrichment, at the point of interception. This capability applies across both ArcGIS Enterprise and standalone ArcGIS Server deployments.

Software components and roles

Service interceptors follow a developer-administrator workflow, with each role carrying distinct responsibilities throughout the interceptor lifecycle. Developers create interceptors using Java, the only supported language, and package them using the tools provided by the ArcGIS Enterprise SDK. Administrators then register these interceptors with ArcGIS Server to activate them.

Once registered, a service interceptor begins intercepting all incoming service traffic but only executes its logic on services that match a specified URL filtering pattern defined in the interceptor’s implementation. Multiple service interceptors can be registered. The order in which they run is controlled by the administrator in a process called chaining. The first interceptor in a chain is able to review the inputs first and is the last one to review the outputs. The second interceptor in the chain is the second to review the inputs and the second-to-last one to review the outputs.

Developer

The developer is responsible for creating service interceptors using the ArcGIS Enterprise SDK. The process involves the following steps:

1. Installing the ArcGIS Enterprise SDK and its prerequisites on the development machine.
2. Using the Maven archetype installed and configured by the ArcGIS Enterprise SDK to bootstrap development.
3. Writing the interceptor logic in Java. To get started with writing a service interceptor and packaging its code into an .interceptor file (custom deployment package) for deployment, see Quick tour of service interceptors.

Administrator

The administrator is responsible for deploying and managing service interceptors within an ArcGIS Enterprise or a standalone ArcGIS Server environment. The administrator decides which services the interceptor runs on. The process involves the following steps:

1. Registering the .interceptor file with ArcGIS Server.
2. Managing interceptor properties, such as the URL pattern and description.
3. Enabling or disabling interceptors as needed.
4. Defining the execution order when chaining multiple interceptors.

Once deployed, service interceptors activate immediately and start intercepting requests from target services, enabling organizations to extend and customize the behavior of their services in innovative and impactful ways.

Relationship between service interceptors and SOIs

Both service interceptors and server object interceptors (SOIs) provide extensibility in ArcGIS Enterprise by enabling the execution of custom logic during service requests.

When choosing the right option for you, remember that it doesn't have to be one or the other. Server interceptors and SOIs are designed to work together and can fulfill different purposes in your organization.

Differences between service interceptors and SOIs

SOIs are designed to extend the functionality of map and image services. They intercept and may modify service requests and responses, allowing developers to override or enhance existing service behaviors in ways that remain transparent to clients such as ArcGIS Pro, Map Viewer, and custom applications. Key characteristics of an SOI include:

• Tied to individual service—Once an SOI is registered with ArcGIS Server, it must be explicitly enabled on each target map or image service.
• Tight integration with service internals—An SOI executes within the server object context of a service and has fine-grained access to internal service objects and configuration details.
• Powerful native APIs—Developers can interact with service configuration, layers, and underlying data sources through ArcObjects and other native APIs.
• Supported languages—An SOI can be developed using Java or .NET.
• Protocol support—An SOI can intercept REST, SOAP, and OGC (e.g., WMS, WFS) requests.
• Developer experience—Building an SOI generally requires familiarity with ArcObjects and the internal architecture of map and image services.

Service interceptors, on the other hand, provide a more service-agnostic and lightweight approach to interception. Key characteristics of a service interceptor include:

• Global activation—Once registered with ArcGIS Server, a service interceptor is automatically activated and applies to all services that match the specified URL filtering pattern, without requiring individual service configuration.
• REST-only scope—Interception is currently limited to REST-based services; support for SOAP and OGC protocols is not available at this time.
• Limited-service configuration details—A service interceptor executes within the REST handler context and does not have access to internal service configurations or underlying data sources. Available metadata includes user identity, service name, service type, and provider information.
• Simplified development model—A service interceptor is written only in Java and does not require knowledge of ArcObjects, making it more accessible to Java developers without prior experience with ArcObjects.

In essence, SOIs offer deep customization for map and image services, providing full access to internal APIs, while service interceptors offer a broader, REST-centric interception mechanism that is easier to implement and maintain across various service types.

Compatibility of service interceptors and SOIs

It is important to note that service interceptors do not replace SOIs. Instead, both extensibility patterns are designed to complement one another and can coexist within the same ArcGIS Enterprise or standalone ArcGIS Server environment. Service Interceptors and SOIs serve different purposes and operate at different layers within the service architecture:

• Service Interceptors focus on high-level request and response interception for any REST-based service and are ideal for lightweight, cross-service logic such as logging, authentication, or data transformation.
• In contrast, SOIs are deeply integrated with map and image services, allowing direct interaction with the internal service model, operations, and data.

By combining both patterns, organizations can implement powerful, multi-layered customizations tailored to their specific business and technical requirements. For example, a map service could utilize the following:

• A service interceptor to perform user authentication, audit logging, or request validation.

• An SOI to manipulate map outputs (including watermarks in backgrounds while accessing map or image services), restrict access to specific layers or data (implementing masking for certain map areas), or dynamically alter the rendering behavior.

Both interceptors can be applied to the same service to fulfill different roles within the request lifecycle and extend ArcGIS Enterprise in a cohesive and modular way.

Key resources

To get started with service interceptors, refer to the following essential resources available in this documentation:

1. System requirements

   The system requirements and prerequisites for developing service interceptors.

2. Quick tour of service interceptors

   A detailed walk-through of developing, building, and deploying a sample service interceptor project.

3. Overview of interfaces

   In-depth descriptions of all key interfaces for implementing service interceptors in ArcGIS Enterprise, including their responsibilities and usage.

4. Samples

   Ready-to-use code examples that demonstrate common patterns and best practices.

5. API reference

   Complete Java API documentation for all service interceptor interfaces and classes, including methods, annotations, and usage notes.