Resource Types

A resource can be classified as singular or a collection. For example, 'get activities' is a collection and 'get activity' is singular. You can identify the collection using the URI /rest/ofscCore/v1/activities and the singular using the URI /rest/ofscCore/v1/activities/{activityId}.

Singular

It represents a single entity or a record, such as an activity. It may have a hierarchical structure that includes child resources. It has a links property to support HATEOAS, which is one of the most important constraints of REST resources. The links property defines the links to related resources. Each link object includes the following properties:

  • rel: Defines the relation to the target resource. The common relations are:
    • Self link (rel="self"): Identifies the link's context in the response.
    • Canonical link (rel="canonical"): Provides the preferred version of the resource URI.
    • Child link (rel=child"): Provides a link to a child resource.
    • LOV link (rel="lov"): Provides a link to a resource containing a valid list of values to be used when setting a field.
    • Parent link (rel="parent"): Links back to its parent resource.
  • href: A URI for accessing the resource.

The following example shows the structure for 'get activity' (/rest/ofscCore/v1/activities/4224031):


{
    "activityId": 4224031,
    "resourceId": "33001",
    "resourceInternalId": 3000001,
    "recordType": "regular",
    "status": "pending",
    "activityType": "4",
    "duration": 39,
    "travelTime": 30,
    "language": "en",
    "languageISO": "en-US",
    "timeZone": "(UTC-05:00) New York - Eastern Time (ET)",
    "timeZoneIANA": "America/New_York",
    "timeOfBooking": "2018-07-18 03:39:51",
    "timeOfAssignment": "2018-07-18 03:41:47",
    "firstManualOperation": "UNSCHEDULE",
    "firstManualOperationUser": "admin",
    "resourceTimeZone": "(UTC-05:00) New York - Eastern Time (ET)",
    "resourceTimeZoneIANA": "America/New_York",
    "resourceTimeZoneDiff": -300,
    "WO_TYPE": "5",
    "requiredInventories": {
        "links": [
            {
                "rel": "canonical",
                "href": "https://<instance_name>.etadirect.com/rest/ofscCore/v1/activities/4224031/requiredInventories"
            }
        ]
    },
    "linkedActivities": {
        "links": [
            {
                "rel": "canonical",
                "href": "https://<instance_name>.etadirect.com/rest/ofscCore/v1/activities/4224031/linkedActivities"
            }
        ]
    },
    "resourcePreferences": {
        "links": [
            {
                "rel": "canonical",
                "href": "https://<instance_name>.etadirect.com/rest/ofscCore/v1/activities/4224031/resourcePreferences"
            }
        ]
    },
    "workSkills": {
        "links": [
            {
                "rel": "canonical",
                "href": "https://<instance_name>.etadirect.com/rest/ofscCore/v1/activities/4224031/workSkills"
            }
        ]
    },
    "links": [
        {
            "rel": "canonical",
            "href": "https://<instance_name>.etadirect.com/rest/ofscCore/v1/activities/4224031"
        },
        {
            "rel": "describedby",
            "href": "https://<instance_name>.etadirect.com/rest/ofscCore/v1/metadata-catalog/activities"
        }
    ]
}

Collection

A collection represents a list of entities or records, such as a list of activities. It has the following characteristics:

  • Extends the singular entity, supporting the links property.
  • Supports requests in parts resulting in a paginated response. The client can get a portion of the collection in one request followed by multiple such requests for the next or previous portion. Hence, the links section may have the following navigation options:
    • Previous link (rel=prev): It points to the previous page.
    • Next link (rel=next): It points to the next page.
  • Functions either as a top-level resource or a subresource.
  • Contains an array of entities/records of the same type. The client can use the orderBy command to enforce a specific order. Otherwise, the order of the items returned can't be determined.

In addition, collection support the following parameters related to querying and paging.

Parameter Description

items

Includes an array of items in the collection. Each item is a singular resource.

totalResults

An integer value that specifies the total number of the resource instances. It includes instances in the current response and the instances that have not been retrieved yet.

limit

An integer value that specifies the paging size that the server uses when serving a client request. For example, the client may request a paging size value of 100, but the server may adjust the value to 25 to improve application performance.

offset

An integer value that specifies the index of the first item to be returned. The offset property index begins at 0 and can't be negative.

For example:
  • If the offset parameter is set to zero (offset=0), then the response contains all items starting from the first item in the collection.
  • If the offset parameter is set to 10 (offset=10) and the count set to 20 (count=20), then the response contains resources from 11 to 30.

hasMore

A Boolean value that indicates whether there are more items to be retrieved. The valid values are as follows:

  • True to indicate there are more values to retrieve.
  • False to indicate there are no more values to retrieve.

For more information, see Paginating in Manage Collections.

The following example shows the structure of the collection for 'get activities' with resources, includeNonScheduled, limit, and offset parameters provided (/rest/ofscCore/v1/activities?resources=22&includeNonScheduled=true&limit=5&offset=2):


{
    "items": [
        {
            "activityId": 3969764,
            "resourceId": "33023",
            "status": "pending"
        },
        {
            "activityId": 4214011,
            "resourceId": "33300000",
            "status": "pending"
        },
        {
            "activityId": 4214012,
            "resourceId": "33300000",
            "status": "pending"
        }
    ],
    "offset": "2",
    "limit": "5",
    "links": [
        {
            "rel": "canonical",
            "href": "https://<instance_name>.etadirect.com/rest/ofscCore/v1/activities?resources=22&includeNonScheduled=true&limit=5&offset=2"
        },
        {
            "rel": "prev",
            "href": "https://<instance_name>.etadirect.com/rest/ofscCore/v1/activities?resources=22&includeNonScheduled=true&limit=2&offset=0"
        }
    ]
}