URI-part is an identifier for a resource's URI, allowing us to never deal directly with the URI string. For more information, see Resource Identifiers.

To define an identifier part, use the <uri-part/> element:

  <uri-part>
    <name>car-id</name>
    <description>Identifier for one car</description>
  </uri-part>
        

Entity resources are used to provide access to some form of data. An entity resource definition consists of and <entity/> definition an a corresponding <resource/> definition.

The definition of an entity itself is as follows:

  <entity>
    <name>car</name>
    <description>A car.</description>
    <property>
      <name>brand</name>
      <description>The brand of the car</description>
      <string/>
    </property>
    <property>
      <name>model</name>
      <description>The model of the car</description>
      <string/>
    </property>
    <property>
      <name>year-build</name>
      <description>The year the car was build</description>
      <integer/>
    </property>
  </entity>
        

An entity must have a <name>, <description>, and at least one <property>. The property must have a data type: in the example above, these are defined by the <string/> and </integer> elements. Cortex provides support for a number of "primitive" property types, including string, integer, long, boolean, and decimal. See the XML schema for the full list of supported types.

The resource part of an entity resource links the URI-part to the entity, and provides a name which can be used to access both.

To define the Entity Resource for a given entity:

  <resource>
    <name>car</name>
    <description>A car resource.</description>
    <uri>/{base.family}/{car-id}</uri>
    <entity>car</entity>
  </resource>
        

You can extend entities by using <is-a/>. There are two ways of extending an entity: inheritance and composition. You can extend an entity within its same family, or with an outside family.

In the API definition schema, entitles are defined with a <family /> element. Conceptually similar entities. For example different types of cars are defined within the 'cars' family.

A dynamic entity resource is an entity resource which operates on an entity containing dynamic properties. These dynamic properties can be used if the properties to be contained in an entity are not known when modeling the API definition or the entity returned by the entity resource contains different properties depending on the state.

  <resource>
    <name>truck</name>
    <description>A truck resource with a dynamic truck entity.</description>
    <uri>/{base.family}/{truck-id}</uri>
    <entity>truck</entity>
  </resource>
        

Note: make sure when injecting a dynamic property entity to validate if the property keys you are expecting are actually contained in the dynamic property map.

For more information on dynamic entities, see Dynamic Fields.

Alias resources are used to create a redirect to another resource. For example, given the following resource:

  <resource>
    <name>color</name>
    <description>A resource that represents a color</description>
    <uri>/{base.family}/{base.scope}/{color-id}</uri>
    <entity>color</entity>
  </resource>
        

An alias resource can be defined as follows:

  <resource>
    <name>default-color</name>
    <description>A resource that represents the default color, it is an alias to the color resource</description>
    <uri>/{base.family}/{base.scope}/default</uri>
    <alias>color</alias>
  </resource>
        

Alias resources only support READ operations.

List resources represent collections or sets of other resources.

To define a list resource:

  <resource>
    <name>countries</name>
    <description>A list of countries resource.</description>
    <uri>/{base.family}/{base.scope}</uri>
    <list-of>country</list-of>
  </resource>
        

Where the <list-of/> element is the name of a resource.

List resources support READ and CREATE operations.

List resources always return all elements of a collection of other resources. Sometimes collections can contain a lot of elements and returning the whole collection might lead to poor performance. A paginated list resource returns a subset of the elements of a collection, with a defined number of items of the collection. To achieve this, a paginated list resource divides the collection into even sized buckets of elements. Each bucket can be accessed individually by accessing the paginated list resource parametrized.

To define a paginated list resource:

  <resource>
    <name>paginated-countries</name>
    <description>A list of countries resource.</description>
    <uri>/{countries}/pages/{page-id}</uri>
    <paginates>country</paginates>
  </resource>
        

Where the <paginates/> element is the name of the collected resource.

Paginated list resources support the READ operation.

When creating an element that should be added to the collection, use a list resource and perform a CREATE operation on it (you don't necessarily have to implement the READ operation of the list resource for this).

A Link point resource has no representation on its own: it has a name, description and URI attributes. Link point resources exist only to provide a place for links to be attached to.

The root resource is a good example of a link point. It does not represent a particular data type itself, like a cart or an order, but provides a resource where links can be attached.

To define a link point resource:

  <resource>
    <name>bookmarks</name>
    <description>bookmarks resource</description>
    <uri>/{base.family}/bookmarks</uri>
  </resource>
        

This snippet defines a link point resource called bookmarks. To attach links to this resource, we would define one or more <relationship/> elements with (in this case) bookmarks as the <from/> reference. See Relationships for more information.

Selector Resources are used when a state of a resource is modifiable by selection of choices.

The different selection choices are either in the state choice or chosen. Choice reflects that a selection could be chosen and chosen reflects that a selection is chosen.

A selector resource definition consists of two resources. First, a selector resource to declare which resource it will act as a selector for, using the <selector-for/> element:

  <resource>
    <name>billingaddress-info-selector</name>
    <description>Selects the billing address to use for an order.</description>
    <uri>{billingaddress-info}/selector</uri>
    <selector-for>billingaddress-info</selector-for>
  </resource>
        

Second, a choice resource to declare what type of resources can be chosen from, using the <choices-for/> element:

  <resource>
    <name>billingaddress-info-selector-choice</name>
    <description>A choice for the billing address selector.></description>
    <uri>{billingaddress-info-selector}/{address}</uri>
    <choices-for>billingaddress-info-selector</choices-for>
  </resource>
        

In the example, a choice between different addresses is modeled. This is defined by the URI identifier-part {address}, which points to the address resource. By convention, the choice resource also to declare which selector resource it is associated with. The <choices-for> tag serves this purpose.

A form resource combines an entity, action-rel and result into a single resource. This provides the following functionality:

• A READ form prototype to retrieve form data
• An action link which links a POST operation from the READ operation,
• A POST form prototype which processes the form's posted data.

  <resource>
    <name>create-order-form</name>
    <description>Create order form resource</description>
    <uri>{item}/form</uri>
    <form>
      <entity>create-order-form</entity>
      <action-rel>submit-action</action-rel>
      <result>order</result>
    </form>
  </resource>
         

An advisor is used to give advice on a resource operation.

There are two types of advises with different semantics: Non-blocking Advisors and Blocking Advisors. For more information, see Advisors.