Skip to main content
Previous section   Next section

Modifying the Specification Class

This chapter summarizes how and why to modify the specification class for a REST service.

This chapter assumes that you have previously generated REST service classes as described in the chapters “Using the /api/mgmnt Service to Create REST Services,” “Using the ^%REST Routine to Create REST Services,” or “Using the %REST.API Class to Create REST Services.”

This chapter discusses the following topics:

Overview

The following table lists reasons for modifying the specification class and briefly summarizes the needed changes:

Reason Changes
To update or replace the specification Modify the OpenAPI XData block manually or by regenerating the specification class.
Enable REST service to support CORS Modify the OpenAPI XData block manually; also add a class parameter and create a custom dispatch superclass. See the chapter “Supporting CORS in REST Services.”
Enable REST service to support web session Add a class parameter. See the chapter “Using Web Sessions with REST.”
Specify privileges needed to use endpoints Modify the OpenAPI XData block manually. See the chapter “Securing REST Services.”
Override the default content type, response character set, or input stream handling Add class parameters. See the next section of this chapter.
Specify a non-default name for a service method Modify the OpenAPI XData block manually. See “Overriding the Name of a Service Method” in this chapter.

Whenever you compile the specification class, the compiler regenerates the dispatch class in the same package and updates the implementation class (see “How InterSystems Updates the Implementation Class,” earlier in this book).

Overriding the Content Type, Response Character Set, or Input Stream Handling

You can override several key aspects of the REST service simply by adding class parameters to the specification class and recompiling.

  • By default, the REST service expects the application/json content type. To override this, add the following to the specification class:

    Parameter CONTENTTYPE = "some-content-type";
    Copy code to clipboard

    Where some-content-type is a MIME content type.

  • By default, the response messages of the REST service are in UTF-8. To override this, add the following to the specification class:

    Parameter CHARSET = "some-character-set";
    Copy code to clipboard

    Where some-content-type-here is the name of a character set.

  • By default, the REST service converts input character streams to Unicode. To not do this, add the following to the specification class:

    Parameter CONVERTINPUTSTREAM = 0";
    Copy code to clipboard

Then recompile. These changes are then copied to the dispatch class.

Overriding the Name of a Service Method

By default, the compiler uses the operationId of an operation to determine the name of method invoked by the corresponding REST call. You can specify a different name. To do so, add the following to the operation within the OpenAPI XData block of the specification class:

"x-ISC_ServiceMethod":"alternatename"
Copy code to clipboard

For example:

    "/pets":{
      "get":{
        "description":"Returns all pets from the system that the user has access to",
        "operationId":"findPets",
        "x-ISC_ServiceMethod":"ReturnPets",
        "produces":[
          "application/json",
          "application/xml",
          "text/xml",
          "text/html"
        ],
Copy code to clipboard

Then recompile. The compiler then adds this new method to the dispatch and implementation classes. Be sure to edit the implementation class and provide an implementation for this new method.