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:
- Enter the following URL in your browser:
http://<application-server>/<context-root>/openAPI.html
The Swagger UI opens forPerson
metaclass. - 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, enterjson?filter=<LocalUser>
. Separate multiple classes with a space, for example,json?filter=<LocalUser Person>
.
You can specify additional criteria in thejson?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, wheren
is the level, for example,json?filter=LocalUser/0
. The default value forn
, if not specified, is1
. - 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.
- An asterisk (*) to filter using wildcard functionality, for example,
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:
- 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 theLocalUser
class, enterjson?filter=<LocalUser>
. Separate multiple classes with a space, for example,json?filter=<LocalUser> Person
. You can specify additional criteria in thejson? 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.
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.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:
- In NexJ Studio, in the Integration tab, select the Services tab.
- Right-click and select Services.
The New Services dialog opens. - 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. - Select the Diagram tab.
- In the Palette, select Script.
- Click a location on the line between the start and end of the service.
- In the Property Editor tab, in the General tab, provide values in the following fields:
Name
Provide a script name. For example, enterscrHandleRequest
.
Caption
Provide a script caption. For example, enterHandle Request
. In the Source tab, enter the following code:
SCHEME(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 theLocalUser
class, enter (httpServer'filter "<LocalUser>"
). Separate multiple classes with a space, for example, (httpServer'filter "<LocalUser> Person"
). You can specify additional criteria in thehttpServer'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, wheren
is the level, for example,httpServer'filter="LocalUser/0"
. The default value forn
, if not specified, is1
.
• 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:TEXT;additional httpServer properties can be set here (httpServer'documented <#t>) (httpServer'filter "<LocalUser>") (httpServer'scope "<behavior>") (httpServer'indenting <#t>)
- 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:
- In NexJ Studio, in the Integration tab, select the Channels tab.
- Right-click and select New Channel.
The New Channel dialog opens. - In the Name field, provide a name for the channel. In Channel Type, select
HTTP
. Click
The New Channel dialog closes and the channel opens in the channel editor. 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, enterapplication/json; charset=UTF-8
.
Authentication Component
Specify the authentication method, for example, enterSystem.Authentication.Basic
orSystem.Authentication.Perimeter
.Info
Only basic authentication is supported with Swagger.
- In the Service Bindings tab, click the Add button to add a new service binding.
- 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
. - 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>