Skip to main content

Using the %REST.API Class to Create REST Services

This chapter describes how to use the %REST.API class to create, update, and delete REST services.

After you generate the classes, see “Modifying the Implementation Class” and the chapters after that.

Using the %REST.API Class to Create or Update a REST Service

The recommended way to create a REST service is to start with the OpenAPI 2.0 specification of the REST service and use that to generate the REST service classes. To use the %REST.API class to do this:

  1. Obtain the OpenAPI 2.0 specification for the REST service, in JSON format, and save the specification as a file.

    The file must be UTF-8 encoded.

  2. In the namespace where you want to define the REST service, use the file to create an instance of %DynamicObject.

  3. Then call the CreateApplication() method of the %REST.API class. This method has the following signature:

    classmethod CreateApplication(applicationName As %String, 
                                  swagger As %DynamicObject = "", 
                                  ByRef features, 
                                  Output newApplication As %Boolean, 
                                  Output internalError As %Boolean) 
                                  as %Status


    • applicationName is the name of the package where you want to generate the classes.

    • swagger is the instance of %DynamicObject that represents the OpenAPI 2.0 specification.

      You can also specify this argument as the URL of a specification, the pathname of a file that contains a specification, or as an empty string.

    • features, which must be passed by reference, is a multidimensional array that holds any additional options:

      • If features("addPing") is 1 and if swagger is an empty string, then the generated classes include a ping() method for testing purposes.

      • If features("strict") is 1 (the default), then InterSystems checks all the properties in the specification. If features("strict") is 0, then only the properties that are needed for code generation are checked.

    • newApplication, which is returned as output, is a boolean value that indicates whether the method created a new application (true) or updated an existing application.

    • internalError, which is returned as output, is a boolean value that indicates whether an internal error occurred.

    If the method generates a new application, InterSystems IRIS creates the disp, impl, and spec classes in the given package.

    If the method updates an existing application, InterSystems IRIS regenerates the disp and spec classes in the given package and updates the impl class, preserving edits you made to that class.

    If the OpenAPI 2.0 specification is invalid, the method does not make any change.

  4. Create a web application that access the REST service, as described in “Creating the Web Application,” earlier in this book.

  5. Define the implementation as described in the chapter “Modifying the Implementation Class.”

The following shows an example of the first steps:

 set file="c:/2downloads/petstore.json"
 set obj = ##class(%DynamicAbstractObject).%FromJSON(file)
 do ##class(%REST.API).CreateApplication("petstore",.obj,,.new,.error)
 //examine error and decide how to proceed...

Using the %REST.API Class to Delete a REST Service

To use the %REST.API class to delete a REST service:

  1. In the namespace where the REST service can be found, call the DeleteApplication() method of the %REST.API class. This method has the following signature:

    classmethod DeleteApplication(applicationName As %String) as %Status

    Where applicationName is the name of the package that contains the REST service classes.

  2. (Optionally) Manually delete the implementation class.

    For safety, the class method does not automatically delete the implementation class, because that class can potentially contain a significant amount of customization.

  3. Delete the web application you created previously (if any) for this REST service. To do so:

    1. In the Management Portal, click System Administration > Security > Applications > Web Applications.

    2. Click Delete in the row that lists the web application.

    3. Click OK to confirm the deletion.