Posted Nov 15 by AppWorks Developer.
Updated Nov 06 by Simon Day.

OpenText with the release of AppWorks introduced a common API standard that allows a developer to access all OpenText products in a consistent, easy to use manner. Targetted at developers wishing to develop their own AppWorks Service.

Last activity Nov 06 by Simon Day.
27900 views. 0 comments.
API

Case Considerations

URLs are all lowercase with no underscores, dashes, or camel case.

Parameters are all snake_case.

Responses - all response fields are snake_case.


URL Structure

A URL identifies a resource. A noun is the only item that is valid within a RESTful URL.

URI Notes
/dogs Valid noun.
/GetAllDogs RPC style. Verbs violates the standard.

NOTE: Any URLs containing a verb prior to the '?' are non-compliant.

URL types

There are only 2 types of URLs for a given resource. One URL interacts with the collection, and another URL interacts with the element.
NOTE: All collections are pluralized.

URI Method Notes
/dogs GETThis returns a collection of dogs.
/dogs/1234 GETThis returns the full content of the dogs element identified by the given key of 1234.

Associations

Associations are a way to drill down within an element to an underlying collection.

URI Method Notes
/owners/123/dogs GETFor a specific owner, get all of his dogs
/owners/123/dogs/1234 GETThis returns the full content of the dogs element identified by the given key of 1234 for owner identified by key 123.

Filtering

Filtering allows you to further drill down within a collection and return only the items matching the filter.
To avoid name collisions the field you are filtering on needs to have a where_ prefix added to the field.

URI Method Notes
/owners/123/dogs?where_color=tan&where_had_shots=true PATCHFor a specific owner, get all the dogs that are tan in color and are up to date on vaccinations.

Limiting which fields are returned by the API

The ability to select and chose the returned fields goes a long way in letting the API consumer minimize network traffic and speed up their own usage of the API.

Use a fields parameter that takes a comma separated list of fields to include in the API result.

URI Method Notes
/dogs?fields=breed,color PATCHGet all the dogs and return only the breed and color.

Sorting Results

To sort the results, you can use the sort parameter. A prefix ( asc_ , desc_ ) will specify the direction. If nothing is specified, asc is implied.

URI Method Notes
/dogs?sort=asc_breed GETGet all the dogs and sort by breed ascending
/dogs?sort=desc_breed GETGet all the dogs and sort by breed descending
/dogs?sort=desc_breed,name GETGet all the dogs and sort by breed descending, name ascending( default applied ).

Expanding Results

Often a result set will contain an entry that the end user may want to see the contents expanded. This would avoid an extra API call per fetched row. An example would be an element in a dogs collection where the owner's info section can optionally be expanded. To expand the contents in a result, use the &expand parameter.

URI Method Returned Data
/dogs/1234?fields=owner,name GET
{    "dogs": [
    {
        "owner": {
            "name": "John Smith",
            "url": "/owners/2134"
        }
        "name": "johnny"
    }
    ]
}
/dogs/1234?fields=owner,name&expand=owner DELETE
{    "dogs": [
    {    "name": "johnny",
        "owner": {
        "name": "John Smith",
        "address" : "123 main st".
        "age" : "21",
        "location": "waterloo Ontario"
        }
    }
    ]
}

Pagination

Every API call needs to support pagination when calling against a collection. The term limit will determine the maximum number of items to return. The terms before and after will determine the direction.

URI Method Notes
/dogs?after=0&limit=20 GETGet all the dogs in the collection, up to a max of 20, starting at the next item after 0.
/dogs?after=2&limit=20 GETGet all the dogs in the collection starting at the next item after 2.
/dogs?before=4&limit=20 GETGet all the dogs in the collection starting at the next item before 4 and going backwards.

The values for before and after are implementation dependent.

Versioning

Every API contains a version string as part of the URL.
The version is as far to the left within the URL as possible.
The version always contains the letter v followed by the current version as a whole number.

EXAMPLE: /v1/dogs/1234

Verbs

In this section, we will cover which verbs (actions) are required to produce a compliant API.

The 4 HTTP verbs that are mandatory to support are: POST, GET, PUT, and DELETE. A 5th optional verb is PATCH ( used to

partially update a resource ).

These 4 verbs align with the standard CRUD functions shown below:

CRUD            Verb
CREATE          POST
READ            GET
UPDATE          PUT
DELETE          DELETE
PARTIAL UPDATE  PATCH   

POST

POST is the only acceptable way to create a new object within a collection.
Exception: In systems where you can specify an ID as part of the object creation, PUT is valid.

URI Method Notes
/dogs POSTOn success, a new dog is added to the dogs collection.
/dogs/1234 POSTError. This method is not allowed.

On success, the response must contain the structure of the new element created.
Optional tip: Create a location header as well.
Must support fields passed on the URL and in the body of the post.

GET

GET is only ever used for reads. A GET can never alter the element or collection.

URI Method Notes
/dogs GETThis returns a collection of dogs.
/dogs/1234 GETThis returns the full content of the dogs element identified by the given key of 1234.

Fetching a Binary Object

We need a way to differentiate between a metadata fetch and a content (binary) fetch.

URI Method Notes
/v4/nodes/123454 GETThis returns the metadata about node 12354.
/v4/nodes/123454/contents(optional extension) GETThis returns the actual document.

Note: The previous response should contain a direct URL for any object that is binary downloadable.

PUT

PUT ideally contains the full object representation. On systems where the optional verb PATCH is supported, the expectation is the full object representation is provided. On success, the response must contain the entire structure of the newly modified element.

URI Method Notes
/dogs/1234?name=fido PUTRenames dog

DELETE

DELETE is the only acceptable way to remove an item from your system.

URI Method Notes
/dogs/1234 DELETEDeletes dog 1234 from the dogs collection.
/dogs DELETEDeletes the entire dog collection.

PATCH

PATCH is the only acceptable way to partially update an element.

URI Method Notes
/dogs/1234?name=fido PATCHRenames dog 1234 to fido

Handling Limited Verb Clients

Some clients can only successfully call GET. Some can only successfully call GET and POST.
We support these clients through the use of the method parameter. The responses from these calls should be identical to the response obtained by making the call in a traditional fashion.

URI Method Notes
/dogs/1234?method=DELETE POSTDeletes dog 1234 from the dogs collection
/dogs/1234?name=max&method=PUT POSTRenames dog to max.


Response Formats

The only mandatory response format for OpenText is JavaScript Object Notation (JSON). If an API developer has a business case that demands XML or any other format, that format can be requested in one of two ways:

  1. Adding the format as a suffix to the collection/element.
  2. Specifying the response format using the accept header.

If nothing is specified, the default response will be JSON.

Response Codes

Standard response code are presented below:

CODE    MEANING
200     OK
202     Accepted
204     OK, No Content returned
301     Redirect, Moved Permanently
400     Bad request
401     Unauthorized
403     Forbidden
404     Not found
405     Method not allowed
409     Conflict
429     Too many requests
500     Internal server error

In addition to the response code, return a valid JSON response containing all of the information necessary to debug the problem.

{"response_code" : "401", 
"message" : "Verbose, plain language description of the problem with hints about how to fix it."
"more_info" : "http://developer.Application.opentext.com/someapi/errors/12345",
"code" : 12345}

In the fourthcoming releases of the AppWorks Developer the error structure will return a link to the documentation relative to the error.


Cross Domain Requests

Browsers will refuse to return data from a domain that is different from the page it was loaded from. For example, a Content Server page wants to load a feed from the Tempo Social API. The call will not return data.
All public APIs support cross-domain requests. Since all public APIs are exclusively exposed to developers through the Application Gateway, the task falls to the Gateway team to support this use case.

Cross domain requests are supported in the following ways:

  1. CORS ( Cross-origin resource sharing )
  2. UMP ( Uniform messaging policy )
  3. *** Cross domain files ( Flash and Silverlight )

Authentication

Each public API supports OpenText Directory Services (OTDS).

Security

All gateway production deployments will be HTTPS ONLY.
All access tokens will be sent within the headers of an API call.
All passwords will be passed by POST only and will be contained within the post body.
Response codes should not confirm the existence of a resource.


Table of Contents

Your comment

To leave a comment, please sign in.