T3.4: Creates REST Services

Overview

InterSystems IRIS provides a comprehensive framework for creating RESTful web services that follow the OpenAPI 2.0 specification. A complete REST service consists of four components working together: the specification class, dispatch class, implementation class, and web application.

Specification Class

The specification class (extending %REST.Spec) serves as the contract definition, containing an XData block with the complete OpenAPI 2.0 specification in JSON format. This specification defines all endpoints, HTTP methods, parameters, request/response formats, and documentation.

Dispatch Class

The dispatch class (extending %CSP.REST) is automatically generated from the specification and should never be manually edited. It handles HTTP request routing, validates incoming requests against the specification, performs content-type checking, and invokes the appropriate implementation methods.

Implementation Class

The implementation class (extending %REST.Impl) is where developers write the actual business logic. It contains stub methods initially generated from the specification that developers then complete with database queries, calculations, and data transformations. The %REST.Impl superclass provides essential utility methods like %SetStatusCode(), %SetHeader(), %WriteResponse(), and %ReportRESTError() for controlling HTTP responses.

Web Application Configuration

The web application configuration in the Management Portal connects everything together, specifying the dispatch class, enabling REST functionality, and controlling security settings.

Naming Convention and Class Regeneration

InterSystems enforces a strict naming convention: given application name "myapp", the classes are named myapp.spec, myapp.disp, and myapp.impl, with the default web application path /csp/myapp. When the specification class is recompiled, the dispatch class regenerates automatically and the implementation class updates intelligently, preserving developer code while adding new stub methods for new endpoints.

Overview

InterSystems IRIS supports two distinct approaches for REST service development, each with specific use cases and tradeoffs.

Specification-First Approach (Recommended)

The specification-first approach, introduced in IRIS 2019.2 and now recommended, begins with creating or obtaining an OpenAPI 2.0 specification document that formally defines the REST API contract. This JSON specification describes all endpoints, HTTP methods, parameters, request/response schemas, content types, and human-readable documentation. Developers use the API management tools (/api/mgmnt service, ^%REST routine, or %REST.API class) to generate the three-class structure automatically. The major advantages include automatic code generation reducing manual errors, built-in support for regeneration when specifications change, interactive documentation via Swagger UI, clear separation of contract from implementation, and easier collaboration between API designers and implementers.

Code-First Approach (Legacy)

The code-first approach, used before 2019.2 and still supported, involves manually creating a class that extends %CSP.REST directly, defining a URLMap XData block that maps URL patterns to ObjectScript methods, and implementing those methods in the same class or separate implementation classes. This approach offers faster initial development for simple services, no requirement to learn OpenAPI specification format, and complete control over routing logic and error handling. However, it lacks automatic documentation generation, requires manual updates for all changes, and doesn't integrate with all API management tools.

Migration and Best Practices

For manually-coded services, InterSystems provides utilities to generate OpenAPI specifications retroactively for documentation purposes. Best practices recommend specification-first for production services, team collaboration, public APIs, and services requiring formal documentation. Code-first may be appropriate for internal prototypes, simple utility endpoints, or services with unusual routing requirements not easily expressed in OpenAPI format. Organizations can also adopt hybrid approaches, starting with manual coding for rapid prototyping and migrating to specification-first when services mature.

Overview

InterSystems IRIS provides comprehensive API management tools that enable developers and administrators to control, monitor, and discover REST services throughout their lifecycle.

The /api/mgmnt Service

The /api/mgmnt service is itself a REST API that provides endpoints for complete service management. Key endpoints include POST /api/mgmnt/v2/:namespace/:application to create new REST services from OpenAPI specifications, GET /api/mgmnt/v2/:namespace/:application to retrieve service specifications in JSON format, DELETE /api/mgmnt/v2/:namespace/:application to remove services, and GET /api/mgmnt/v1/:namespace/restapps to list all REST-enabled web applications. This service accepts OpenAPI 2.0 specifications in JSON format via POST request bodies and can be invoked from tools like Postman, curl, or custom scripts.

The ^%REST Routine

The ^%REST routine provides a simpler command-line interface accessible from the IRIS terminal, useful for quick operations during development without requiring HTTP tools.

The %REST.API Class

The %REST.API class offers programmatic access to the same functionality, with class methods like CreateApplication(), UpdateApplication(), DeleteApplication(), GetAllRESTApps(), and GetRESTApps() that return %Status values for error handling. These methods return %ListOfObjects containing %REST.Application instances with detailed information about each service.

Discovery Capabilities

Discovery capabilities are particularly valuable in large deployments, allowing administrators to inventory all REST services, identify which namespaces contain which services, retrieve OpenAPI specifications for documentation, and verify web application configurations. The tools support both specification-first services (with .spec classes) and manually-coded services (without .spec classes), though some operations like regeneration only work with specification-first services.

Logging and Integration

Logging can be configured to track API management operations, service creation timestamps, specification changes, and errors during code generation. These logs are essential for troubleshooting deployment issues and maintaining audit trails. Third-party tools integrate well with these management APIs, including Swagger Editor for specification development and validation, Postman collections for testing endpoints, and CI/CD pipelines for automated deployment. Best practices include using /api/mgmnt for automated deployments and integration with external tools, using ^%REST for interactive development sessions, and using %REST.API when building custom administration utilities or dashboards.

Overview

Securing REST services in InterSystems IRIS involves multiple layers of authentication and authorization working together to protect sensitive data and operations.

Authentication Methods

For authentication, IRIS supports three primary mechanisms. HTTP authentication headers are the recommended approach for production REST services, supporting both Basic authentication (username:password base64-encoded) and Bearer token authentication (JWT or OAuth access tokens) sent in the Authorization header. Web session authentication allows credentials in URL query parameters but is less secure and should be avoided for production. OAuth 2.0 provides enterprise-grade authentication with token-based access control.

OAuth 2.0 Implementation

To implement OAuth 2.0, administrators must configure the IRIS instance as an OAuth 2.0 resource server, configure the REST service's web application to use delegated authentication, and create a ZAUTHENTICATE routine in the %SYS namespace that validates incoming OAuth tokens and maps them to IRIS user accounts. InterSystems provides a sample routine (REST.ZAUTHENTICATE.mac) in the Samples-Security GitHub repository that developers can copy and customize. This routine extracts the access token from requests, validates it against the authorization server, retrieves user claims, and establishes the IRIS security context.

Authorization with RBAC

For authorization (controlling what authenticated users can do), IRIS uses role-based access control (RBAC) with resources and privileges. Developers specify required privileges using the OpenAPI extension property x-ISC_RequiredResource in the specification class. This property can appear in the info object to protect the entire service or in individual operation objects to protect specific endpoints. The value is an array of resource:mode pairs like ["PatientData:READ","Prescriptions:WRITE"]. When the specification compiles, these requirements are embedded in the dispatch class, which automatically performs authorization checks before invoking implementation methods. If users lack required privileges, they receive HTTP 403 Forbidden responses. Additionally, the SECURITYRESOURCE parameter of %CSP.REST provides class-level protection, requiring specific resource access before any endpoint can be invoked.

Web Application Security and Best Practices

The web application configuration in the Management Portal provides another security layer, controlling allowed authentication methods (Password, Unauthenticated, Kerberos, Delegated), enabling SSL/TLS requirements, and setting password policies. Best practices include always using HTTPS in production to encrypt credentials in transit, implementing OAuth 2.0 for public-facing APIs and microservices architectures, using x-ISC_RequiredResource for fine-grained endpoint protection, regularly rotating JWT signing keys, implementing token expiration and refresh workflows, logging authentication failures for security monitoring, and never embedding credentials in client-side code or URLs.

Overview

Effective REST API documentation is critical for developer adoption, maintenance, and long-term success. InterSystems IRIS's specification-first approach inherently supports comprehensive documentation through the OpenAPI 2.0 specification format. The specification serves as both executable contract and human-readable documentation.

OpenAPI Description Fields

Developers should populate all description fields throughout the OpenAPI specification, including the info object (API overview, version, contact information, license), operation objects (what each endpoint does, expected behavior, edge cases), parameter objects (purpose of each parameter, valid value ranges, default values), response objects (success and error scenarios, status codes, response structures), and schema objects (data models, field meanings, constraints). The x-ISC extensions used by InterSystems should also be documented for maintainers.

Swagger UI Integration

Once the specification is complete, Swagger UI provides interactive documentation that developers can access through web browsers. To set up Swagger UI, organizations can host their own instance or use the public Swagger Editor online. The documentation displays all endpoints organized by tags, shows HTTP methods with appropriate color coding, allows developers to execute test requests directly from the documentation, displays request/response examples with syntax highlighting, and shows parameter requirements and data types.

Accessing Specifications Programmatically

InterSystems IRIS exposes OpenAPI specifications through the GET /api/mgmnt/v2/:namespace/:application endpoint, which returns the complete specification in JSON format. This endpoint can be used directly with Swagger UI by entering the URL in the Swagger UI explorer box. For static documentation, third-party tools can generate HTML, PDF, or Markdown documentation from OpenAPI specifications, useful for offline distribution or embedding in larger documentation sets.

Documentation Best Practices

Additional documentation best practices include maintaining a changelog in the info.description field tracking API version changes, using meaningful operationId values that describe operations clearly, providing realistic examples in parameter and response descriptions, documenting all possible HTTP status codes including error conditions, explaining authentication requirements explicitly, including rate limiting and quota information if applicable, providing code examples for common operations in multiple languages, and maintaining separate specifications for different API versions. The specification class itself should include ObjectScript comments explaining complex business logic in the implementation class, particularly database query optimization, data transformation rules, and error handling strategies. For manually-coded REST services without specification classes, developers can still generate OpenAPI specifications using the API management tools for documentation purposes. Organizations should establish documentation review processes, ensuring specifications are updated when endpoints change, reviewing documentation for clarity and completeness before releases, and gathering feedback from API consumers to improve documentation quality. Well-documented REST services reduce support burden, accelerate developer onboarding, minimize integration errors, and improve overall API adoption rates.