Model services

Documentation for the JSON version of the REST interface may be accessed at <serverRoot>/openAPI.html. It also gives you the opportunity to try it out. For example: http://localhost:7080/training/openAPI.html.

Model Services provide API access to the Business Model for REST style create, read, update, delete, and invoke.  They are available at <serverRoot>/<format>/<objectType>/<id>?<parameters> along with an HTTP Method to indicate the CRUD (create, read, update, delete) verb.

If you don't specify an "attributes" parameter, all public primitive attributes are returned.

If you do specify a list of primitive attributes in the attributes parameter, then only those attributes will be returned.

e.g. (firstName lastName)

Associated objects can be retrieved using nested lists in the attributes parameter. Simply specify a non-primitive attribute name then a list of one or more attributes. For example:

firstName lastName (addrs city state zip))

These nestings can continue. For example:

(firstName lastName (addrs city state zip (type name)))

Attributes can also be retrieved polymorphically - meaning attributes that only exist on subclasses can be retrieved when reading the base class. (see examples below)

Attribute names in the where and order by parameters may take the simple form <attributeName> or alternatively (@ <attributeName>). The second form is recommended. In this case, the "@" represents the current instance and may be used to traverse arbitrarily long association paths. For example, on User we may specify:

(= (@ person homeAddress city) "Toronto")

[{
      "$class": "Person",
      "$oid": "10031C7A7EF46D45ADBC72090BCCD04825",
      "lastName": "Cotherman",
      "addrs": [
         {
            "$class": "Address",
            "$oid": "10EE388953279847C6B7DB63CACAB774C0",
            "state": null,
            "zip": null,
            "type": {
               "$class": "AddressType",
               "$oid": "1000000000000010008000CEEDED004000",
               "name": "Business"
            },
            "city": null
         }
      ],
      "firstName": "Joseph",
      "initials": null
   }

]

$class and $oid

The $class and $oid attributes of an object are always returned.

They are the class name of the object and unique identifier respectively.

Request Structure

Model Services are available at <serverRoot>/<format>/<objectType>/<id>?<parameters> along with an HTTP Method to indicate the CRUD verb.  

serverRoot 

The host and context root of the server. For example: http://localhost:7080/training.

This is defined in your environment file.

format 

Defines the return type for the request.  Formats supported include "json", "xml", and "web" for a SOAP encoding. These endpoints support the REST style requests discussed here. We use the json format for all of the examples in this document.  To see the effect of another protocol, simply replace json with xml or web in the examples. Additionally, there are other supported protocols including soap and text but they use a different API style called Generic RPC and are not discussed here.  

objectType 

Specifies the object type to work on e.g. Person, Household, or Account

id 

An optional unique identifier for the item to work on.  If there is no id in the URL, the request will work on a collection, if there is one, it will work on a specific instance. For example: http://localhost:7080/training/json/Person/101DBCCB4F0B4E4345BDD1C68ECE20DBBD?$indent.

parameters

The parameters, attributes, where, orderby, count and offset, employ the same syntax as with any object query (in other words, the same syntax used in scripting for reads).

$indent 

Pretty print the output.

We include the $indent parameter in many of the following examples. It is only for readability and is not required.

attributes

The list of attributes, or associated objects, to proactively retrieve. To retrieve all primitive attributes, leave this parameter out.  To retrieve selected primitive attributes or just the id of associated objects, list them in the brackets. For example: http://localhost:7080/training/json/Person?attributes=(firstName lastName initials addrs)&$indent.

To traverse association paths you can wrap associated objects in brackets then list their primitive and associated attributes.  This can be done recursively as seen here. For example: http://localhost:7080/training/json/Person?attributes=(firstName lastName initials (addrs city state zip (type name)))&$indent.

{
      "$class": "Person",
      "$oid": "10031C7A7EF46D45ADBC72090BCCD04825",
      "lastName": "Cotherman",
      "addrs": [
         {
            "$class": "Address",
            "$oid": "10EE388953279847C6B7DB63CACAB774C0",
            "state": null,
            "zip": null,
            "type": {
               "$class": "AddressType",
               "$oid": "1000000000000010008000CEEDED004000",
               "name": "Business"
            },
            "city": null
         }
      ],
      "firstName": "Joseph",
      "initials": null
   },

Two special (read advanced 🙂) syntax exist for downcast and annotations. 

Attribute downcast syntax (@@) - Polymorphic read is used to proactively load subclass specific attributes when reading from a base class.  In the following example we only retrieve the homePhone attribute for Entity records that are of type Person, otherwise we don't include it.

http://localhost:7080/training/json/Entity?attributes=(fullName lastName (@@ Person firstName homePhone))&$indent

Annotations syntax - create calculated attributes on-the-fly

In this example, return the lastName attribute, a calculated _lnLen attribute which is the length of the last name, and a _fullName calculated attribute.  We use the underscore here just to avoid name collisions. For example:

http://localhost:7080/training/json/Person?attributes=(lastName (: _lnLen (string-length (@ lastName))) (: _fullName (string-append (@ lastName) (@ firstName))))&$indent

Aggregate functions - can be applied to subcollections on instances. Supported operators include count, average, min, max, sum. For example:

http://localhost:7080/training/json/Person?attributes=(firstName lastName (: _countryCnt (count (@ addrs country))) (: _uniqueCountryCnt (count (unique (@ addrs country)))) (: _nullCodeCnt (count (null? (@ addrs zip)))) (: _avg (average (string-length (@ addrs city)))) (: _min (minimum (string-length (@ addrs city)))) (: _max (maximum (@ addrs city))) (: _sum (sum (string-length (@ addrs city)))))&$indent

where

The where clause. The following examples illustrate the use of associations, reverse associations and qualified associations.

Simple where not using the @ syntax - (and ( = firstName "Tim") (= lastName "Lamont"))

Simple where using the @ syntax - (and ( = (@ firstName) "Joe") (= (@ lastName) "Test"))

Any operator - Reduces the multiplicity of an association to 1 

Expressing queries that are impossible to do only with joins. In this example, return people who have at least one address in Toronto and at least one in Richmond Hill. Nothing will be returned by the equals operator equivalent (and (= (@ addrs city) "Toronto") (= (@ addrs city) "Richmond Hill"))

(and (any (= (@ addrs city) "Toronto")) (any (= (@ addrs city) "Richmond Hill"))) ; two part association path

Optimizing database filtering on collection associations. In this example, the database will return only one person record per matching addresses vs returning as many copies of a person record as there are matching addresses when using the equals operator equivalent (Person'read ... '(= (@ addrs city) "Toronto") ...)

(any (= (@ addrs city) "Toronto") ; two part association path

Conditions in where clause association paths.  This syntax allows us to restrict parts of association paths to specific subclasses and also to apply arbitrary conditions on association paths.

The most common use case: limit an association based on a qualifier e.g. look for all Entities with a user named "Shaw" playing their advisor role

(= (@ coverage (= (@ coverageRole roleName) "Advisor") userPerson lastName) "Shaw")

Subclass restriction example: note that homeAddress is an attribute that is only found on the Person subclass of Entity

(= (@ entity (instance? (@) Person) homeAddress city) "Toronto")

Arbitrary condition example: reads all instances of the Telcom class that has an entity with a lastname of "Shaw" that has an address in "Toronto" with and address2 line that is not null.

(not (null? (@ entity (= (@ lastName) "Shaw") addrs (= (@ city) "Toronto") address2)))

Note

Conditions may be applied in reverse associations as well as forward associations

Reverse association syntax (@@).  Used to query from the end of an association "back" to the class you are reading.  Forward associations take the form (@ part1 part2 part3 ...). The @ represents an instance of the class being read. Revese associations take the form (@@ <ClassName> part3 part2 part1) where part1 represents an attribute with a type of the class being read. You can usually just navigate the forward association, but you may see this syntax if you are tracing requests from NexJ UI clients.

Address?where=(= (@@ User person addrs) <userId>)

orderBy

The expressions on which to order the collection - a list of (<sort-expr> . <ascending?>) pairs.

E.g. (((@ firstName) . #t) ((@ lastName) . #f)) or more simply (since it is a single associate path length) ((firstName . #t) (lastName . #f)) 

count

The number of instances to retrieve. Null '() for the default value of -1, meaning up to the readLimit specified in the data source.  One cannot pass in a larger count than readLimit defined in the data source.

offset

The number of top level instances to skip from the beginning of the retrieved collection. Default value of 0.

HTTP Method

Maps as follows.  GET=read, POST=create or invoke, PUT=update, DELETE=delete

Body

The body of the request when creating, updating, or optionally deleting is an object structure similar to that returned during a read (or GET).