OpenAPI Description File
You can use an OpenAPI Document to interact with the HTTP REST API of RaptorXML Server. This can be useful not only for discovering and understanding the features of the HTTP REST API, but also to test specific HTTP requests before generating code that implements these requests.
Your installation of RaptorXML Server contains an OpenAPI Document file in YAML format, which you can try out or extend. This file is located in the Examples folder of your RaptorXML Server installation. On Windows, the file location is: C:\Program Files\Altova\RaptorXMLXBRLServer2026\examples\raptorxbrl_http_rest_api.yaml. On Linux, go to the RaptorXML Server Examples folder.
OpenAPI Document in Swagger Editor
You can interact with Raptor's HTTP API by opening the sample OpenAPI Document file (see above) in Swagger Editor (screenshot below) and sending requests to the HTTP API. The editor's left pane shows the description file's YAML code, and the right pane shows the interactive interface generated by Swagger Editor. When you edit the code in the left pane, the changes are shown directly in the right pane. The interactive interface enables you to enter the details of HTTP requests, to execute these requests, and to view the server responses. The mechanism for sending requests to RaptorXML Server's HTTP API and receiving responses is described in the section Client Requests.
Connect to the server
To connect to RaptorXML Server via its HTTP API, you must enter the address details of the server machine on which RaptorXML Server is hosted. You can do this either in the YAML code of the OpenAPI file or in the appropriate data entry fields in the right-hand pane (see screenshot above). The default server address in the OpenAPI file is localhost:8087.
Note: Make sure that the RaptorXML Server service has been started (Windows, Linux) before you send your HTTP requests.
You can test whether the connection is correct by sending a GET /version request. This is the first request of the description file (screenshot below). In the right pane, first click Try it out and then Execute.
The version information will be displayed in the Responses section of the GET request box (see screenshot above). If you get an error, you can clear the response, fix the error, and execute again. Common errors are a failed connection, which might be because RaptorXML Server has not been correctly started or licensed.
POST a request, GET the server response
To send an HTTP request, do the following. In the right-hand interactive pane, click the Try it out of the POST /queue method and, in the msg entry field (see screenshot below), enter your POST request. For example, in the screenshot below, we have entered a request for the valxml-withxsd (xsi) command to check the validity of the NanonullOrg.xml file, as follows:
{
"command": "xsi",
"options": {
"verbose": true
},
"args": [
"file:///C:/Test/OpenAPI/NanonullOrg.xml"
]
}
We do not need to supply the XSD file because the XML file contains a reference to the XSD file in it. (The XML file and its referenced XSD files are located in the Examples folder of the RaptorXML Server installation folder, but we have copied them to a separate work folder; see URL in the screenshot.)
For more information about the syntax of the message, see Initiating Jobs with POST. For information about the various commands available in RaptorXML Server, see Command Line Interface (CLI).
After entering the message of the request, click Execute. The server response, containing a Job ID and a Job Result Document, will be displayed immediately below the request and will look something like the screenshot below.
You can check the result document to see the details of the server response. Use the GET /results/{jobId} request to get the URI of the result document. Alternatively, you can construct the URI by appending the "result" part of the server response (see screenshot above) to the server address (for example, http://localhost:8087/).
For more information about server responses, see the topics Server Response to POST Request, Getting the Result Document, and Getting Error/Message/Output Documents.
Other HTTP requests
You can use other HTTP requests defined in the OpenAPI file. The screenshot below shows the available requests. Note that RaptorXML Server functionality is requested via POST. The subsequent GET requests are used to retrieve the various result documents, including output documents and error documents.
The paths shown after each method button is the path that is appended to the {server address}/v1. For example, if the server address is http://localhost:8087, then the full path of some requests are given below. Note that parameters in braces must be supplied in the request.
GET /version
http://localhost:8087/v1/version
GET /results/{jobId}
http://localhost:8087/v1/results/{jobId}
where
{jobId} is the Job ID returned by the server on receiving a request via the POST queue. When you enter this Job ID in the GET /results request, the server returns the URI of the Result Document together with its own Job ID (the SubJob ID).
GET /results/{subJobId}/output/{fileName}
http://localhost:8087/v1/results/{subJobId}/output/{fileName}
where
{subJobId} is the Job ID returned by the server on executing the GET /results request
{fileName} is the name of an output file or an error file that was returned on executing a GET /results request. See Getting Error/Message/Output Documents for details.