Working with the Model Services OpenAPI Module

Model Services over JSON/REST

Model Services are one of three API approaches for accessing business model data and functionality from MODL Server. The other two ways are SOA Services and Custom Integration Services.

Model Services provide secure direct access to the business model. It is available over REST (XML and JSON), SOAP, JSON RPC, and TRPC. MODL Server’s JSON/REST endpoint can be found at <context root>/json.

The following request https://localhost:7443/nexj/json/Person?attributes=(firstName%20lastName%20fullName%20(addrs%20city%20state%20(type%20name)))&count=4&where=(=%20lastName%20%22Lamont%22)&$indent results in something like the following:

[
   {
      "$class": "Person",
      "$oid": "1077A80B0250044D3D838D2EE8B8734ED0",
      "lastName": "Lamont",
      "addrs": [
         {
            "$class": "Address",
            "$oid": "104D59AE6A223E49998FD26AEB83971072",
            "state": "ON",
            "type": {
               "$class": "AddressType",
               "$oid": "1000000000000010008000CEEDED004000",
               "name": "Business"
            },
            "city": "Scarborough"
         },
         {
            "$class": "Address",
            "$oid": "10E42406DC9C5A4E1EB9DC3FEE3A9B9D9C",
            "state": "ON",
            "type": {
               "$class": "AddressType",
               "$oid": "1000000000000010008000CEEDED004001",
               "name": "Home"
            },
            "city": "Toronto"
         }
      ],
      "fullName": "Lamont, Dionne",
      "firstName": "Dionne"
   },
   {
      "$class": "Person",
      "$oid": "1084DA273965C8409AB644E63474C7B419",
      "lastName": "Lamont",
      "addrs": [
         {
            "$class": "Address",
            "$oid": "10B007B8337AF2448B8A3E413C6022CFAE",
            "state": "ON",
            "type": {
               "$class": "AddressType",
               "$oid": "1000000000000010008000CEEDED004000",
               "name": "Business"
            },
            "city": "Toronto"
         },...

OpenAPI

Background

The OpenAPI Specification, originally known as the Swagger Specification, is a specification for machine-readable interface files for describing, producing, consuming, and visualizing RESTful web services. A variety of tools can generate code, documentation and test cases given an interface file. You can find more information at https://en.wikipedia.org/wiki/OpenAPI_Specification.

MODL Server provides OpenAPI output at <context root>/json. Depending on your model, this output can be very large. So NexJ provides a way of filtering the output to only include the classes you are interested in.

filter parameter

To filter the items in your output, you can use the filter parameter. filter=className/n

For example, to specify that this service should return information for the LocalUser class, enter json?filter=LocalUser. Separate multiple classes with a space, for example, json?filter=LocalUser Person. Additional options include:

• An asterisk (*) for wildcard functionality, for example, json?filter=*User
• A forward slash followed by a numeric value (/n) to include associated classes, where n is the level, for example, json?filter=LocalUser/0. The default value for n, if not specified, is 1
• A greater than sign (>) to include the parent metaclasses of the specified class, for example, json?filter=LocalUser>
• A less than sign (<) to include the derived metaclasses of the specified class, for example, json?filter=LocalUser<.

Note
The relative order of /n and < matters. For example, /n< includes associated subclasses and </n does not.

$indent parameter

Makes the returned JSON more readable (but slightly larger). e.g. https://localhost:7443/nexj/json/Person?attributes=(firstName%20(addrs%20city%20state))&count=2&$indent

This output can be used in any OpenAPI/Swagger viewer or code generation tool.

Interactive UI

This option improves on the raw JSON returned by the OpenAPI endpoint. Interactive documentation of the model may be accessed at <context root>/openAPI.html.

This interactive document provides “how to” information on the model server REST interface. The documentation contains:

• A section for each class.
• Its methods, parameters, types and an “Execute” button.
• A list of information models with documentation.

To see details on a particular method, simply press on its button. Here you will see a description of any parameters, available responses, and the response structure along with the “Execute” button.

The Execute button

The “Execute” button allows you to try things out. Simply, press the “Execute” button, fill out your parameters, then press the “Execute” button (which has now moved to the bottom of the parameters). When this runs as expected, you will receive a 200 response. The output includes a Curl representation and http url of the request, the response code and body, then the http headers.

Caution
If you try a request and it fails, but your parameters look fine, check the quotations you are using. Especially, if you cut and past the parameter from documentation in your browser. Some browser and font combinations will mean an example may be encoded wrong. For instance, if you use (= (@ lastName) “Lamont”) as the where clause parameter, you will get a 500 server response. Retype the quotes manually and things should work fine.

Setting up the Interactive OpenAPI UI

To include the interactive UI capabilities in your project, add the openapi mixin module. This mixin is applicable for version 8.4 and beyond. It is currently not added to the finance environment by default.

To enable this capability, add the following to your environment file, within the <Mixins> </Mixins> tags

<Mixin namespace="nexj:openapi" version="0"/>

This mixin module can be used in any project.