Using the /api/mgmnt Service

This chapter describes how to use the /api/mgmnt service to create, update, and delete REST services. It discusses the following:

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

The /api/mgmnt service also provides options you can use to discover and document web services as described later in this book.

Using the /api/mgmnt Service to Create a REST Service

The recommended way to create a REST service is to create an OpenAPI 2.0 (also called Swagger) description for the REST service and use that to generate the REST service classes. If you are implementing a REST service defined by a third party, they may provide this OpenAPI 2.0 description. See the OpenAPI 2.0 SpecificationOpens in a new window for details about the format of an OpenAPI 2.0 description. The following topics describe how to use the /api/mgmnt service to do this.

Using the /api/mgmnt Service to Generate the Classes

In the first step, generate the REST service classes, as follows:

Create or obtain the OpenAPI 2.0 description of the REST service, in JSON format.
Obtain a REST testing tool such as PostMan (https://www.getpostman.com/Opens in a new window).
In the testing tool, create an HTTP request message as follows:
- For the HTTP action, select or specify POST.
- For the URL, specify a URL of the following form:
  
  http://localhost:52773/api/mgmnt/v2/namespace/myapp
  
  Where localhost is the name of the server, 52773 is the web server port on which InterSystems IRIS is running, namespace is the namespace where you want to create the REST service, and myapp is the name of the package where you want to create the classes.
- For the request body, paste the OpenAPI 2.0 description of your web service, in JSON format.
- Specify the request body type as JSON (application/json)
- Provide values for the IRISUsername and IRISPassword parameters. For IRISUsername, specify a user that is a member of the %Developer role and that has read/write access to the given namespace.
Send the request message.

If the call is successful, InterSystems IRIS creates the disp, impl, and spec classes in the given package and namespace.
In the testing tool, check the response message. If the request was successful, the response message will look like the following example:
```
{
    "msg": "New application myapp created"
}
```

To complete the basic REST service, create an InterSystems web application and define the implementation (see the chapter “Modifying the Implementation Class”). You can do these steps in either order.

Creating the Web Application

In this step, you create a web application that provides access to your REST service. In the Management Portal, complete the following steps:

Click System Administration > Security > Applications > Web Applications.
Click Create New Web Application.
Specify the following values:
- Name — Name for the web application; this must be unique within this instance of InterSystems IRIS. The most common name is based on the namespace in which the web application runs: /csp/namespace
- Namespace — Select the namespace in which you generated the classes.
- Enable Application — Select this check box.
- Enable — Select REST.
- Dispatch Class — Type the fully qualified name of the dispatch class. This should always be package.disp where package is the name of the package that contains the generated classes.
For information on other options on this page, see Create an Application.
Click Save.

Using the /api/mgmnt Service to Update a REST Service

The InterSystems API management tools enable you to update the generated classes without making changes to your edits in the implementation class. The class is regenerated if necessary, but your edits are preserved.

To update a REST service, use the steps listed in “Using the /api/mgmnt Service to Generate the Classes.”

If the update was successful, InterSystems IRIS regenerates the disp and spec classes in the given package and updates the impl class, preserving edits you made to that class. The response message will look like the following example:

{
    "msg": "Application myapp updated"
}

How InterSystems Updates the Implementation Class

If you previously edited the impl class, InterSystems preserves those edits as follows:

The implementations of all methods are left as is.
Any new class members you added are left as is.

However, InterSystems regenerates the description (the /// comments) of the class and of each generated method. If the signature of any implementation method changes (for example, because the specification has changed), InterSystems updates the signature and adds the following comment to that class method:

/// WARNING: This method's signature has changed.

Using the /api/mgmnt Service to Delete a REST Service

The InterSystems API management tools also enable you to delete a REST service easily. To do so:

Using a REST testing tool, create an HTTP request message as follows:
- For the HTTP action, select or specify DELETE.
- For the URL, specify a URL of the following form:
  
  http://localhost:52773/api/mgmnt/v2/namespace/myapp
  
  Where localhost is the name of the server, 52773 is the web server port on which InterSystems IRIS is running, namespace is the namespace where you want to create the REST service, and myapp is the name of the package that contains the REST service classes.
- Provide values for the IRISUsername and IRISPassword parameters. For IRISUsername, specify a user that is a member of the %Developer role and that has read/write access to the given namespace.
Send the request message.

If the call is successful, InterSystems IRIS deletes the disp and spec classes within the given package and namespace.

InterSystems IRIS does not, however, delete the impl class.
In the testing tool, check the response message. If the request was successful, the response message will look like the following example:
```
{
    "msg": "Application myapp deleted"
}
```
Manually delete the implementation class.

For safety, the /api/mgmnt service does not automatically delete the implementation class, because that class can potentially contain a significant amount of customization.
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.