NexJ Logo

Accessing JSON objects using a RESTful connection

You can access a JSON object by providing a URL to the RESTful endpoint or you can configure a channel to communicate with the endpoint.

You can view available commands for a metaclass in either of the following ways:

  • By displaying the Swagger UI for the metaclass in the Swagger UI. Swagger UI is an open source tool that displays API resources in an easy-to-read format.
  • By retrieving the raw Swagger Interface Definition Language (IDL) for the metaclass and pasting the raw data into an API Editor.

Info

The Swagger UI only supports NexJ CRM version 8.4 and later.

Accessing JSON objects using Swagger UI

You can use Swagger UI to view all available operations for a metaclass in an easy-to-read format.

To view metaclass operations in Swagger UI, you must add the following mixin to your environment file in NexJ Studio and then restart your application server:
<Mixin namespace="nexj:openapi" version="0"/>

To access JSON objects using Swagger UI:

  1. Enter the following URL in your browser:
    http://<application-server>/<context-root>/openAPI.html
    The Swagger UI opens for Person metaclass.
  2. Edit the filter criteria in the search box to view the Swagger UI for the desired metaclass. For example, to view the Swagger UI for the LocalUser metaclass, enter json?filter=<LocalUser>. Separate multiple classes with a space, for example, json?filter=<LocalUser Person>.
    You can specify additional criteria in the json?filter function. Use:
    • An asterisk (*) to filter using 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<.

      Info

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

  3. Click Explore.
    Swagger UI displays the operations you can access for the specified metaclass.

You have accessed JSON objects through a REST endpoint.

Accessing JSON objects using an API Editor

You can access JSON objects by providing a URL to a RESTful endpoint. You can display the generated Swagger IDL in an API editor and also view and update data for the individual JSON objects defined by IDL.

To access JSON objects using an API Editor:

  1. To get the Swagger IDL for a metaclass, enter the following URL in your browser:
    http://<application-server>/<context-root>/json?filter=<filtervalue>&$indent
    Where:
    application-server
    Specifies the URL for a NexJ CRM instance.
    context-root
    Specifies the context root of the NexJ CRM instance, for example, <nexj>.
    json?filter=<filtervalue>
    Specifies filter criteria for the schema to be generated. For example, to specify that this service should be enabled for the LocalUser class, enter json?filter=<LocalUser>. Separate multiple classes with a space, for example, json?filter=<LocalUser> Person. You can specify additional criteria in the json? filter function. Use:
    An asterisk (*) to filter using 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<.
      Enables indenting of the RESTful response to make it easier to read the response.

    • The following URL returns the Swagger IDL for the LocalUser class on a local installation of NexJ CRM.
      http://<localhost>:7080/<nexj>/json?filter=<LocalUser>/0&$indent
      The Swagger IDL is returned for the class in your browser. Copy the raw data of the Swagger output.

  2. Paste the raw data into an API editor, such as Swagger Editor. In the editor, view the syntax for available commands. For example, view available commands for the get LocalUser command.

  3. Using information from the API editor, enter a URL formatted to perform an operation using the RESTful API. For example, the following example returns instances of the LocalUser class.
    http://<application-server>/<context-root>/json/LocalUser?$indent

You have accessed JSON objects through a REST endpoint.

Configuring channel security for RESTful connections

You can configure security for a RESTful connection by creating a channel that accesses the REST endpoint and a service that contains configurable parameters for the RESTful endpoint. For example, you can specify the authentication method and limit the classes which can be defined by the generated Interface Definition Language (IDL).

Creating a service for a RESTful connection

Configure a service for a RESTful connection that contains configurable parameters for the RESTful endpoint and binds the service to the HTTP channel configured for the REST endpoint.

To create a service for a RESTful connection:

  1. In NexJ Studio, in the Integration tab, select the Services tab.
  2. Right-click and select Services.
    The New Services dialog opens.
  3. In the Name field, provide a name for the service, for example, enter JSONRESTService. Click Finish.
    The New Service dialog closes and the service opens in the service editor.
  4. Select the Diagram tab.
  5. In the Palette, select Script.
  6. Click a location on the line between the start and end of the service.
  7. In the Property Editor tab, in the General tab, provide values in the following fields:
    Name
    Provide a script name. For example, enter scrHandleRequest.
    Caption
    Provide a script caption. For example, enter Handle Request.

  8. In the Source tab, enter the following code:

    (define httpServer ((invocation-context)'getComponentInstance "HTTPServer.JSON"))

(httpServer'pathOffset 1)

;additional httpServer properties can be set here
(httpServer'documented #t)
(httpServer'filter "<filtervalue>")
(httpServer'scope "<scopetype>")
(httpServer'indenting <#t>)

(message
      (: body httpServer)
)


    Where:
    (httpServer'documented #t)
    Specifies whether to add schema documentation to the schema that is generated when the service URL is accessed. Valid values are #t and #f. The default value is #f.
    (httpServer'filter "<filtervalue>")
    Specifies filter criteria for the generated schema. For example, to specify that this service should be enabled for the LocalUser class, enter (httpServer'filter "<LocalUser>"). Separate multiple classes with a space, for example, (httpServer'filter "<LocalUser> Person"). You can specify additional criteria in the httpServer'filter function. Use:
    • An asterisk (*) to filter using wildcard functionality, for example, httpServer'filter="*User".
    • A forward slash followed by a numeric value (/n) to include associated classes, where n is the level, for example, httpServer'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, httpServer'filter="LocalUser>".
    • A less than sign (<) to include the derived metaclasses of the specified class, for example, httpServer'filter="LocalUser<".

    Info

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


    (httpServer'scope "<scopetype>")
    Specifies the scope for the generated schema. Valid values are generic, state, and behavior. The default value is behavior:
    • generic sets the scope to generic schema.
    • state sets the scope to generic schema and metaclasses.
    • behavior sets the scope to generic schema, metaclasses, and events.
    (httpServer'indenting <#t>)
    Specifies whether to indent the JSON response to make it easier to read the response. Valid values are #t and #f. The default value is #f.
    For example:

    ;additional httpServer properties can be set here
(httpServer'documented <#t>)
(httpServer'filter "<LocalUser>")
(httpServer'scope "<behavior>")
(httpServer'indenting <#t>)
  9. Save and close the service.

You have created a service for RESTful connection. The following example shows the course for a complete sample service.

<Service layout="startX:50;startY:50;endX:300;endY:50" stream="true">
   <Script caption="Handle Request" layout="y:50;x:130" name="scrHandleRequest"><!
[CDATA[(define httpServer ((invocation-context)'getComponentInstance
 "HTTPServer.JSON"))

(httpServer'pathOffset 1)

;additional httpServer properties can be set here
(httpServer'documented <#t>)
(httpServer'filter "<LocalUser>")
(httpServer'scope "<behavior>")
(httpServer'indenting <#t>)

(message
      (: body httpServer)
)]]></Script>
</Service>

Next, bind the service to the HTTP channel configured for the REST endpoint.

The httpServer properties can also be set as parameters in the REST URL, for example, localhost:7080/nexj/ json?filter=LocalUser&scope=generic. If the httpServer'documented or httpServer'scope parameter is specified both in the REST URL and the REST service, the REST URL parameter overrides the service. If the httpServer'filter parameter is specified in the service, the IDL can only access the classes specified in the service.

Configuring a channel for a RESTful connection

You can configure security for a RESTful connection by creating a channel that accesses the REST endpoint.

You must first create a service to bind to the channel that you will configure for the RESTful endpoint.

To create a channel for a RESTful connection:

  1. In NexJ Studio, in the Integration tab, select the Channels tab.
  2. Right-click and select New Channel.
    The New Channel dialog opens.
  3. In the Name field, provide a name for the channel. In Channel Type, select HTTP. Click Finish.
    The New Channel dialog closes and the channel opens in the channel editor.

  4. In the Overview tab, provide values in the following fields:
    HTTP Methods
    Specify the HTTP methods that the service can perform on the resource. For example, select PUT to enable the service to update a resource in NexJ CRM.

    Info

    The Send method must be set to false.


    Content Type
    Specify the default HTTP mime type of the body of the response or request content. For example, enter application/json; charset=UTF-8.
    Authentication Component
    Specify the authentication method, for example, enter System.Authentication.Basic or System.Authentication.Perimeter.

    Info

    Only basic authentication is supported with Swagger.

  5. In the Service Bindings tab, click the Add button to add a new service binding.
  6. In the General tab, provide values in the following fields:
    Service
    Specify the name of the service that the channel invokes, for example, JSONRESTService.
    Output
    Specify the name of this channel, for example, JSONRESTChannel.
  7. Save and close the channel.

You have configured channel security for a RESTful connection. Changes are reflected in the Source tab as shown in the following example:

<HTTP authComponent="System.Authentication.Basic" binary="false"
 contentType="application/json; charset=UTF-8" delete="true" get="true" put="true"
 send="false">
  <ServiceBindings>
     <ServiceBinding output="JSONREST" service="JSONREST"/>
  </ServiceBindings>
</HTTP>