· May 19, 2020

Cannot create REST Service using the /api/mgmnt Service

I am trying to create REST API following these instructions:

However it does not work.


I tried downloaded the v2.0 schema.json of the OpenAPI specification and pasted it on Postman with the parameters as speicifed, but I get this error message back:

    "msg": "ERROR #8738: Correct OpenAPI 2.0 version was not specified: . <$.swagger>\r\n  > ERROR #5490: Error running generator for method '%OnCompile:TasksRestApp.spec' \r\nERROR: %REST.Spec.cls(%OnCompile) of generated code compiling subclass 'TasksRestApp.spec'\r\n    > ERROR #5030: An error occurred while compiling class 'TasksRestApp.spec'"


So what is the "correct" open API 2.0 version, I downloaded it from the GIT link that is supplied in the instructions? 

I then also tried v3.0 and get this error:

    "msg": "ERROR #8736: OpenAPI 2.0 specification is not valid JSON: Escape sequence invalid 8 Line 60 Offset 12 .\r\n  > ERROR #5490: Error running generator for method '%OnCompile:TasksRestApp.spec' \r\nERROR: %REST.Spec.cls(%OnCompile) of generated code compiling subclass 'TasksRestApp.spec'\r\n    > ERROR #5030: An error occurred while compiling class 'TasksRestApp.spec'"


I list the JSON file I used below. I would also like to add that I tried the Terminal method as well using "do ^%REST" but it yielded the same result:


The V2.0 JSON is
Discussion (4)1
Log in or sign up to continue

Thank you Adam,

I sort of realized that at some point and then thought it is funny, laughing at myself and the way they wrote the documentation. The documentation explicitly states you have to download that specification and supply it, not that you have to create a specification based on that, I quote: 

1. Obtain the OpenAPI 2.0 specification for the REST service, in JSON format.

3. In the testing tool, create an HTTP request message as follows:

The above does state you downlaod the OpenAPI 2.0 specification in JSON format and supply that as the body in Postman, I then thought they will from that create a framework for your REST of some sort that you then fill out with your routes and calls, it is really obscure documentation, for somebody new to InterSystems and to swagger this is very ambiguous. laugh

Thanks for the comment. Is this description clearer?

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 Specification 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:

  1. Create or obtain the OpenAPI 2.0 description of the REST service, in JSON format.

Thanks again and feel free to use the "Help us improve this page" link on any of our documentation pages to send us a comment.