Skip to main content

Using the ^%REST Routine to Create REST Services

This chapter describes how to use the ^%REST routine to create and delete REST services.

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

Tip:

You can also use this routine to update a REST service; simply delete the REST service and then create it again.

Using the ^%REST Routine

The ^%REST routine is a simple command-line interface. At any prompt, you can enter the following answers:

^ Causes the routine to skip back to the previous question.
? Causes the routine to display a message that lists all the current options.
q or quit (not case-sensitive) Ends the routine.

Also, each question displays, in parentheses, the default answer to that question.

Using the ^%REST Routine to Create 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 routine to do this:

  1. Obtain the OpenAPI 2.0 specification for the REST service, in JSON format. Either save the specification as a file or make a note of the URL where the specification can be accessed.

  2. In the Terminal, change to the namespace where you want to define the REST service.

  3. Enter the following command to start the ^%REST routine:

    do ^%REST

  4. At the first prompt, enter a name for the REST service. This name is used as the package name for the generated classes; use a valid package name. If you want to use the name list, l, quit, or q (in any case variation), enclose the name in double quotes. For example: "list"

  5. At the next prompt, enter Y (not case-sensitive) to confirm that you want to create this service.

    The routine then prompts you for the location of the OpenAPI 2.0 specification to use. Enter either a full pathname or a URL.

  6. At the next prompt, enter Y (not case-sensitive) to confirm that you want to use this specification.

    The routine creates the disp, impl, and spec classes within the specified package in this namespace. The routine then displays output like the following:

    -----Creating REST application: myapp-----
CREATE myapp.spec
GENERATE myapp.disp
CREATE myapp.impl
REST application successfully created.

    Next the routine asks if you also want to create a web application. You will use this web application to access the REST service.

  7. At this point, you can do the following:

    • Enter Y (not case-sensitive) to create the web application now.

    • Enter N (not case-sensitive) to end the routine.

      You can create the web application separately as described in “Creating the Web Application,” in the previous chapter.

  8. If you entered Y, the routine then prompts you for the name of the web application.

    The name must be unique within this instance of InterSystems IRIS. The default name is based on the namespace in which the web application runs: /csp/namespace.

    Enter the name of the web application or press return to accept the default name.

    The routine then displays output like the following:

    -----Deploying REST application: myapp-----
Application myapp deployed to /csp/myapp

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

Using the ^%REST Routine to Delete a REST Service

To use the ^%REST routine to delete a REST service:

  1. In the Terminal, change to the namespace where the REST service can be found.

  2. Enter the following command to start the ^%REST routine:

    do ^%REST

  3. At the first prompt, enter a name for the REST service.

    If you are not sure of the name of the REST service, enter L (not case-sensitive). The routine lists all the REST services and then prompts you again for the name of the REST service.

  4. If the routine finds a REST service with the given name, it displays a prompt like the following:

    REST application found: petstore
Do you want to delete the application? Y or N (N):

  5. Enter Y (not case-sensitive) to confirm that you want to delete this service.

  6. (Optionally) Manually delete the implementation class.

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

Next sectionUsing the %REST.API Class to Create REST Services
Previous sectionUsing the /api/mgmnt Service
Feedback