Web Service APIs

REST

The following table describes each HTTP Request and its corresponding adaptor session method that is invoked:

HTTP GET requests act as both get_object() and retrieve_objects() adaptor session calls, depending on the HTTP URI that is specified. All HTTP URIs must specify an adaptorId. When an Object Type and Object Id are also supplied, the GET is treated as a get_object(). When just the adaptorId and Object Type are specified, the GET request is treated as a retrieve_objects() call.

Query Criteria

For retrieve_objects() calls, you may also specify a query criteria, which is passed along to the retrieve_objects(). This is useful if you need to narrow down the search xctx of the retrieve_objects(), or use an index to obtain performance.

Object Options

For both GET requests, you may additionally specify object options to instruct the server on how to construct the object or objects that are being returned. For a complete list of options, see the Object Type description for _AdaptiveQueryCriteria_.

Content Types

Adaptive Framework can be configured for a variety of content types, each of which can be used in the RESTful request/response by specifying the appropriate value for the HTTP Header Content-Type.

It's very easy to demonstrate how to use the RESTful API, using the command-line tool, curl. If you are running afwfcgi and have Apache or Nginx setup on the traditional Secure HTTP port 443, and you wanted to get the object afw of type _AdaptiveAdaptor_, from the core adaptor, afw, and you wanted it to be formatted with whitespace, you could run the following:

curl https://localhost/afw/_AdaptiveAdaptor_;whitespace/afw
{
    "adaptorId": "afw",
    "metrics": {
        "addObjectCount" : 0,
        "deleteObjectCount": 0,
        "getObjectCount": 38422,
        "modifyObjectCount": 0,
        "replaceObjectCount": 0,
        "retrieveObjectsCount": 2370,
        "updateObjectCount": 0
    },
    "properties":{
        "contextualLabel": "Core afw adaptor",
        "adaptorId": "afw",
        "adaptorType": "afw_runtime",
        "type": "adaptor"
    },
    "referenceCount": 3,
    "serviceId": "adaptor-afw"    
}

Perform Actions

The second way to interact with Adaptive Framework remotely is to send HTTP POST payloads to the core adaptor and specify which adaptive functions and parameters you'd like to interact with. This method requires clients to generate and receive payloads, but it offers some functionality that's not available through traditional REST. For example, you can invoke any adaptive function through, not just adaptor session ones. To use this technique, simply use HTTP POST actions to the Core adaptor, afw, along with a payload to instruct the server which adaptive function to invoke and all of its parameters.

Request Format

{
    "actions": [
        {
            "adaptorId": <adaptorId>,
            "function": <adaptive_function_id>
            <parameters...>
        },
        ...
    ]
}

Response Format

{
  "actions": [
      "status": <status_level>,
      {
          "status": <status_level>,
          "result": <result>
      },
      ...
  ]
}

Examples

The following section provides some code samples for how to use a tool such as CURL to interact with adaptive framework by creating, modifying and and retrieving objects in different ways.

Add Object

curl -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     -X POST http://localhost/vault/users \
     -d @- <<EOF 
{
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@myorg.org"
}
EOF

Retrieve Objects

curl -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     http://localhost/vault/users;whitespace;objectId/?firstName=John

Get Object

curl -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     http://localhost/vault/users;whitespace;objectId/1234567890

Replace Object

curl -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     -X PUT http://localhost/vault/users/1234567890 \
     -d @- <<EOF 
{
    "firstName": "Joe",
    "lastName": "Doe",
    "email": "joe.doe@myorg.org"
}
EOF

Modify Object

curl -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     -X POST http://localhost/vault/users/1234567890 \
     -d @- <<EOF 
[
    [
        "set_property",
        "firstName",
        "John"
    ],
    [
        "remove_property",
        "lastName",
        "email"
    ]        
]
EOF

Delete Object

curl -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     -X DELETE http://localhost/vault/users/1234567890