DevonWay REST API Reference
Jump To...
Introduction
DevonWay provides access to data in a safe, secure, and consistent manner through a REST application interface. This guide describes our interface relative to the HTTP/1.1 standards published by W3C. See RFC 2616 for more information on the HTTP/1.1 specification.
Prerequisites
Although we have built our interface on the comparatively simple concepts of REST, we recommend that developers writing client applications be familiar with the REST philosophy, the HTTP protocol, and writing web applications in general. Using this interface does not mandate a specific platform or application stack.
NOTE: The JSON and XML examples in this document have been formatted to make them easier to read. Formatting is not required for request bodies, and response bodies will not be formatted. Field names are examples, and may not represent actual fields.
Getting Started
The DevonWay REST interface supports four basic HTTP verbs: GET, POST, PUT, and DELETE (see Table 1). Other verbs are not supported at this time. Table 2 offers a high-level interpretation of the supported HTTP verbs as they apply to accessing module object instances (data). A detailed discussion of each verb is found in the Verbs section.
Additional common characteristics of the DevonWay REST interface:
- DevonWay resources are accessed by sending an HTTP request to a URL path. The path may vary based on the type of resource you are accessing. This document includes path definitions and examples.
- Additional parameters may be required depending on the context of the request.
- HTTP status codes indicate the success or failure of a call. Additional information may be available in the response body depending on the context of the request.
- JSON or unstructured XML may be used in request and response bodies; use the Accept or Content-Type headers to indicate your preference as needed.
- Requests may include the
Accept-Encoding:gzipheader for smaller response payloads and reduced content download wait times.
DevonWay maintains the following security requirements to protect customer data:
- Authentication parameters are required for access to any and all resources.
- SSL encryption is required for all transactions.
- IP Address whitelisting is required for all transactions.
Further details are available in the Security section.
Table 1: HTTP Verb Support
| HTTP Verb | Supported | Safe* | Idempotent** |
|---|---|---|---|
| GET | X | X | X |
| POST | X | [1] | |
| PUT | X | [2] | |
| DELETE | X | X | |
| HEAD | X | X | X |
| OPTIONS | NOT SUPPORTED | ||
| CONNECT | |||
| TRACE | |||
| PATCH | |||
Table 2: Supported Module Object Activities
| HTTP Verb | Operation | Query Parameters | Request Headers | Request Body |
|---|---|---|---|---|
| GET | Get a specific object | Accept Authorization DWAYSessionId |
||
| GET | Search for objects | q={query} | Accept Authorization DWAYSessionId |
|
| POST | Add a new object | Authorization Content-Type DWAYSessionId |
JSON or XML | |
| PUT | Update an existing object | Authorization Content-Type DWAYSessionId |
JSON or XML | |
| DELETE | Delete an existing object | Authorization DWAYSessionId |
Security
SSL Encryption
All traffic between DevonWay servers and client applications is encrypted using 128-bit SSL. Although DevonWay maintains SSL certificates and encoding/decoding on the server-side, your application must support SSL encoding and decoding on its own.
IP Address Whitelisting
Only transactions from authorized IP addresses will be recognized. Please register your development, testing, and production IP addresses with our Operations team. IP address ranges are supported. See your DevonWay Technical Account Manager for more details.
Authentication
Authentication is required to access any REST resource on DevonWay servers. Two forms of authentication are offered at this time: HTTP Basic and Session Token.
Basic Authentication
This authentication model applies HTTP Basic Authentication as described in RFC2617 where username and password are passed in the request Authentication header. The username and password are the same credentials that a person would use to log into a DevonWay application.
The header must include the keyword "Basic" followed by the username and password separated by a single colon character (":") and Base64 encoded. Header example where the username is "Aladdin" and the password is "open sesame":
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
When the authentication is successful, the server's response will include a new header with a temporary session token. Learn more about this token in the next section.
When unsuccessful, the server will respond with HTTP status code 401 and the request will not be completed.
NOTE: The user must have a role to modify the module's data. Check the Roles tab on the module's definition to confirm proper authorization.
It is important to note that username/password authentication is subject to the your area's password policies. For example, you will receive a 401 response when the password has expired if that policy is in effect for your area. The following policies may return an HTTP status 401 depending on your area and account:
- Password Expiration
- Change Password on First Login
- Too Many Login Attempts
- Inactive Account
Contact your DevonWay technical account manager if you need help managing these policies.
Session Token Authentication
Successfully authenticated requests using HTTP Basic Authentication will receive a proprietary session token in the header of the response; for example:
DWAYSessionId: TWFNSU09OV05QVkFNV1hJVE0xMzA0MjAx MjAzMTMxMjQ0yTAuNjg1
The actual session token may differ in length from the example.
Subsequent API calls need to include the DWAYSessionId header (exactly as it appeared in the initial response) instead of using a Basic Authentication header. This will save a small amount of time with every request made while the session is viable. The session token will expire two hours after its last use. The token is also tied to the caller's IP address.
Auditing
All transactions that add data or modify existing data will be tagged with the originator's username. This information is available on the Object History window for every YourWay object. This information may be used to track changes by user, and may be compiled into audit reports.
Resource Paths
Resource paths are used to access module instances, or objects. Paths include information that is specific to your DevonWay subscription. This information may be obtained from your DevonWay application.
RESTConnect URLs
RESTConnect URLs are composed of two elements: A base URL and an resource path. Your base URL will be different depending on the server you are working with. Development, testing, and production are typically hosted on different servers. Contact your Technical Account Manager for the specific URLs for your area.
A resource path will be appended to the base URL depending on what resource your application working with. Refer to the Verbs for Module Objects section for path definitions and examples.
A full example URL might look like: https://rest-config.devonway.com/RESTConnect/rest/v2/subscribers/ABC1234/modules/RF-TEST
-
Base URL : https://rest-config.devonway.com/RESTConnect
-
Version : /rest/v2
-
Resource : /subscribers/{subscriber code}/modules/{module code}
Subscriber Code
The subscriber code is found on the preferences panel of your application's Admin Dashboard:
Steps for locating the subscriber code:
- Log into your application; you must have Administrator privileges.
- Click the "Admin Dashboard" link in the left navigation area under "Application Administration".
- Click the "Preferences" button on the "Admin Dashboard"
- Copy the subscriber code from the Preferences panel.
Module Code
Every request needs to include a module code; the module code you use depends on the data you want to work with. You can find the module code on the Module Definition panel:
Your Technical Account Manager can provide you the module code if you do not have access to Define Module.
URL Encoding
Query parameters should always be "percent-encoded". For example:
.../subscribers/FXEHS14790/modules/DWFND-PER?q=FirstName%3DJoe%26LastName%3DSmith
Object Identifiers
An object identifier is a sequence of numbers and letters that, along with subscriber code and module code, uniquely identifies an instance of a module. Some identifier examples are: PER 2012-1452 , CV 2011-11330, and ORG 2010-0002.
You will never need to create an object identifier; these are always assigned for you by your DevonWay application. A GET request with a query will return a list of object identifiers. GET requests for specific objects must include the object identifier in the URL.
Note that any space characters appearing in the object identifier must be encoded with "%20" before you include them in a URL.
Module Object Data
Field Codes
DevonWay uses field codes to identify data elements within an object. In the following JSON example, "FirstName" and "LastName" are field codes.
{"FirstName": "Joe", "LastName": Smith"}
A list of field codes can be obtained in two ways:
- You can send a query for an object and analyze the response body. The serialized object will always include all available fields.
- A list of field codes is available under the Web Services tab on Define Module (click the "Field Codes" button under "Module Token"). Contact your Technical Account Manager if you do not have access to Define Module.
There are several key points to remember about field codes.
- Field codes may change during module maintenance depending on the maintenance activity. It is important to coordinate module maintenance with interface testing.
- Field codes are case sensitive. For example, "firstName" is not the same as "FirstName".
Child-Level Rows
Each row in a child-level element will be uniquely identified with a Row_Identifier element. This identifier should be used when changing child-level data during a PUT. In the following JSON example, a row at the "MemberOf" child level includes the identifier "365438":
"MemberOf": [
{
"Row_Identifier": "365438",
"Organization": {
"ModuleCode": "DWFND-ORG",
"Identifier": "ORG 2011-1321"
},
"Attribute": {
"ModuleCode": "DWFND-ATR",
"Identifier": "ATR 2011-3453"
}
}
]
The value of the Row_Identifier element should not be interpreted.
External Object References
DevonWay objects may have references to other DevonWay objects. These references are denoted by the presence of two protected fields, ModuleCode and Identifier:
"Attribute": {
"ModuleCode": "DWFND-ATR",
"Identifier": "ATR 2011-3453"
}
Extra "denormalized" fields may also appear based on "Include" settings in the module definition. When adding a new object with POST or updating an existing object with PUT, object references must always only include ModuleCode and Identifier. Extra fields will result in an error and the operation will not complete. References that cannot be resolved will also result in an error.
Date Fields
Working with date fields may differ depending on the context of your transaction.
Dates in GET Queries
Queries on date fields need to be formatted as YYYYMMDD; components are appended together without a delimiter, and leading zeros are added to single digit months and days. For example, a query for reports created on March 2, 2012 would appear as:
../subscribers/FXEHS14790/modules/DW-RPT?q=ReportDate%3D20120302
Dates in GET, POST, and PUT
When exchanging date fields in GET, POST, or PUT transactions, the dates must appear as YYYY/MM/DD, where each date component is separated with a slash character. Using report date as an example, one would see the following JSON response payload (XML would be similar):
{
"ReportTitle": "March Task Report",
"ReportDate": "2012/03/02",
.
.
.
}
Non-modifiable system fields
When performing POST or PUT transactions, the the following fields should not be included in your response. These are system fields defaulted by the system.
- Identifier
- InitiatedBy
- InitiatedOn
- InitiatorsDepartment
Verbs for Module Objects
GET Object
Retrieve a specific instance of a module by object identifier.
Path:
/subscribers/{subscriber}/modules/{module}/{identifier}
Request Headers:
Accept: application/xml or Accept: application/json
Authorization: Basic [username:password Base64 encoded]
DWaySessionId: [Session key from previous authentication, if available]
Status Codes:
HTTP 200: Success
HTTP 404: Not Found (object ID cannot be resolved)
HTTP 500: Server-side error (see response body)
Sample URL:
https://server/rest/v2/subscribers/ERTSE35233/modules/DWFND-PER/PER%202011-1234
Sample Request Body:
Request body is unused for this operation.
Sample JSON Response:
References to external objects may include some denormalized data as indicated by the external object's relationship.
{
"ReportingAuthority": "DevonWay",
"FirstName": "Joe",
"LastName": "Smith",
"EmployeeId": "ABC1234",
"Status": "Active",
"Manager": {
"ModuleCode": "DWFND-PER",
"Identifier": "PER 2012-1010",
"FullName": "Michael Jackson"
},
"MemberOf": [
{
"Row_Identifier": "365438",
"Organization": {
"ModuleCode": "DWFND-ORG",
"Identifier": "ORG 2011-1321"
},
"Attribute": {
"ModuleCode": "DWFND-ATR",
"Identifier": "ATR 2011-3453"
}
}
],
"Contacts": [
{
"Row_Identifier": "255134",
"Contact": {
"ModuleCode": "DWFND-CV",
"Identifier": "CV 2012-0123"
},
"Value": "555-1234",
"Type": "Office Phone"
},
{
"Row_Identifier": "957324",
"Contact": {
"ModuleCode": "DWFND-CV",
"Identifier": "CV 2012-0124"
},
"Value": "555-8913",
"Type": "Home Phone"
}
]
}
Sample XML Response:
References to external objects may include some denormalized data as indicated by the external object's relationship.
<Module>
<ReportingAuthority>DevonWay</ReportingAuthority>
<FirstName>Joe</FirstName>
<LastName>Smith</LastName>
<EmployeeId>ABC1234</EmployeeId>
<Status>Active</Status>
<Manager>
<ModuleCode>DWFND-PER</ModuleCode>
<Identifier>PER 2011-1198</Identifier>
</Manager>
<MemberOf-array>
<MemberOf>
<Row_Identifier>365438</Row_Identifier>
<Organization>
<ModuleCode>DWFND-ORG</ModuleCode>
<Identifier>ORG 2011-1321</Identifier>
</Organization>
<Attribute>
<ModuleCode>DWFND-ATR</ModuleCode>
<Identifier>ATR 2011-3453</Identifier>
</Attribute>
</MemberOf>
</MemberOf-array>
<Contacts-array>
<Contact>
<Row_Identifier>255134</Row_Identifier>
<Contact>
<ModuleCode>DWFND-CV</ModuleCode>
<identifier>CV 2012-0123</Identifier>
</Contact>
<Value>555-1234</Value>
<Type>Office Phone</type>
</Contact>
<Contact>
<Row_Identifier>957324</Row_Identifier>
<Contact>
<ModuleCode>DWFND-CV</ModuleCode>
<Identifier>CV 2012-0124</Identifier>
</Contact>
<Value>555-9843</Value>
<Type>Home Phone</Type>
</Contact>
</Contacts-array>
</Module>
GET Objects
Retrieve the object identifiers for multiple objects that match the search criteria exactly, including letter case.
A status code 200 and an empty array in the response body indicate that the search completed successfully, but no matching objects were found.
Path:
/subscribers/{subscriber}/modules/{module}?q={query}
Query Parameters:
One parameter "q" is permitted. The query consists of XML tags (obtained from the module definition) and sought values separated by ampersand characters '&'. The query string must be percent encoded before it is assigned to "q=". For example:
Before encoding: q=FirstName=Joe&LastName=Smith
After encoding: q=FirstName%3DJoe%26LastName%3DSmith
Wild card characters and partial matches are not allowed.
Embedded ampersand and equals symbols can be escaped with a leading character, for example:
DeptName=Research && Development
code=alpha==beta
Query Parameter: assignedTo
The parameter "&assignedTo=ME" allows results to be filtered based on their assignment to the signed on user. The following options exist:
ME : User
TE : Teams
AL : Alternates
MT : Person and Teams
MA : Person and Teams and Alternates
MM : Person and Alternates
Response Headers:
Last-Modified: Tue, 08 Sep 2015 21:56:51 GMT
ETag: [ETag value]
Request Headers:
Accept: application/xml or Accept: application/json
Authorization: Basic [username:password Base64 encoded]
DWaySessionId: [Session key from previous authentication, if available]
If-None-Match: [ETag value from previous request. Only available for object GETs]
Status Codes:
HTTP 200: Success
HTTP 404: Not Found (object ID cannot be resolved)
HTTP 500: Server-side error (see response body)
Sample URL:
https://server/rest/v2/subscribers/ERTSE35233/modules/DWFND-PER?q=FirstName%3DJoe%26LastName%3DSmith
Sample Request:
Request body is unused for this operation.
Sample JSON Response:
[
"PER 2011-1432",
"PER 2012-1243",
"PER 2012-1904"
]
Sample XML Response:
<Results-array>
<Identifier>PER 2011-1432</Identifier>
<Identifier>PER 2012-1243</Identifier>
<Identifier>PER 2012-1904</Identifier>
</Results-array>
POST Object
Add a new object instance. If the object is successfully created, the new object's URL will be returned to the caller in the response's Location header.
As with all required fields, it is necessary to include the ReportingAuthority field with new objects. An error may result for POST requests without this field (or any required field).
Path:
/subscribers/{subscriber}/modules/{module}
Request Headers:
Authorization: Basic [username:password Base64 encoded]
DWaySessionId: [Session key from previous authentication, if available]
Content-Type: application/xml or Content-Type: application/json
Status Codes:
HTTP 200: Success
HTTP 404: Not Found (object ID cannot be resolved)
HTTP 500: Server-side error (see response body)
Sample URL:
https://server/rest/v2/subscribers/GFSYF23423/modules/DWFND-PER
Sample JSON Request:
{
"ReportingAuthority": "DevonWay",
"FirstName": "Joe",
"LastName": "Smith",
"EmployeeId": "ABC1234",
"Manager": {
"ModuleCode": "DWFND-PER",
"Identifier": "PER 2011-2052"
},
"Comments": [
{
"Comment": "Joe is a good worker.",
"By": {
"ModuleCode": "DWFND-PER",
"Identifier": "PER 2011-2052"
}
}
],
"Contacts": [
{
"Contact": {
"ModuleCode": "DWFND-CV",
"Identifier": "CV 2012-0123"
}
},
{
"Contact": {
"ModuleCode": "DWFND-CV",
"Identifier": "CV 2012-0124"
}
}
]
}
Sample XML Request:
<Module>
<ReportingAuthority>DevonWay</ReportingAuthority>
<FirstName>Joe</FirstName>
<LastName>Smith</LastName>
<EmployeeId>ABC1234</EmployeeId>
<Manager>
<ModuleCode>DWFND-PER</ModuleCode>
<Identifier>PER 2011-2052</Identifier>
</Manager>
<Comments-array>
<Comment>
<Comment>
Joe is a good worker.
</Comment>
<By>
<ModuleCode>DWFND-PER</ModuleCode>
</Identifier>PER 2011-2052</Identifier>
</By>
</Comment>
</Comments-array>
<Contacts-array>
<Contact>
<Contact>
<ModuleCode>DWFND-CV</ModuleCode>
<Identifier>CV 2012-0123</Identifier>
</Contact>
</Contact>
<Contact>
<Contact>
<ModuleCode>DWFND-CV</ModuleCode>
<Identifier>CV 2012-0124</Identifier>
</Contact>
</Contact>
</Contacts-array>
</Module>
PUT Object
Update an existing module instance by object identifier.
Path:
/subscribers/{subscriber}/modules/{module}/{identifier}
Request Headers:
Authorization: Basic [username:password Base64 encoded]
DWaySessionId: [Session key from previous authentication, if available]
Content-Type: application/xml or Content-Type: application/json
Accept: application/json
Status Codes:
HTTP 200: (Item was successfully updated)
HTTP 404: Not Found (object ID cannot be resolved)
HTTP 500: Server-side error (see response body)
Sample URL:
https://server/rest/v2/subscribers/SGFRW87643/modules/DWFND-PER/PER%202012-0123
Sample JSON Request:
{
"Status": "Inactive",
"Manager": {
"ModuleCode": "DWFND-PER",
"Identifier": "PER 2011-0843"
}
"Comments": [
{
"Comment": "Updating Joe's status and manager",
"By": {
"ModuleCode": "DWFND-PER",
"Identifier": "PER 2011-0843"
}
}
]
}
Sample JSON Resoonse
{
"Comments": [
{
"Row_Identifier": "458297",
"Comment": "Updating Joe's status and manager",
"By": {
"ModuleCode": "DWFND-PER",
"Identifier": "PER 2011-0843"
}
}
]
}
Sample XML Request:
<Module>
<Status>Inactive</Status>
<Manager>
<ModuleCode>DWFND-PER</ModuleCode>
<Identifier>PER 2011-0843</Identifier>
</Manager>
<Comments>
<Comment>
<Comment>
Updating Joe's status and manager
</Comment>
<By>
<ModuleCode>DWFND-PER</ModuleCode>
<Identifier>PER 2011-0843</Identifier>
</By>
</Comment>
</Comments>
<Module>
DELETE Object
Remove a single module instance by object identifier.
Path:
/subscribers/{subscriber}/modules/{module}/{identifier}
Sample URL:
https://server/rest/v2/subscribers/NZDUE63253/modules/DWFND-PER/PER%202012-0123
Request Headers:
Authorization: Basic [username:password Base64 encoded]
DWaySessionId: [Session key from previous authentication, if available]
Status Codes:
HTTP 204: No Content (Item was successfully deleted)
HTTP 404: Not Found (object ID cannot be resolved)
HTTP 500: Server-side error (see response body)
Sample Request:
Request body is unused for this operation.
DELETE Child level data
Remove instance from an child level
Path:
/subscribers/{subscriber}/modules/{module}/{identifier}
Sample URL:
https://server/rest/v2/subscribers/NZDUE63253/modules/DWFND-PER/PER%202012-0123
Request Headers:
Authorization: Basic [username:password Base64 encoded]
DWaySessionId: [Session key from previous authentication, if available]
Content-Type: application/json
Status Codes:
HTTP 204: No Content (Child row was successfully deleted)
HTTP 404: Not Found (object ID cannot be resolved)
HTTP 500: Server-side error (see response body)
Sample Request:
Send the object data structure that contains the child level Row_Identifier values to be deleted. Additional values can be included but are discarded.
{
"Comments": [
{
"Row_Identifier": "458297"
}
]
}
Embedding New Objects
RESTConnect v2 includes a new convenience where developers can embed new external objects as part of a single POST or PUT request. Consider this example where a new Person references a new Contact which in turn references a new ContactType:
In RESTConnect v1, this would've entailed at least three separate requests to the RESTConnect server:
- A POST to create the new contact type object
- A POST to create the new contact object
- And finally, a POST to create the new Person that references the previously created objects
RESTConnect v2 shortcuts this process by allowing new objects to be embedded inside their parents. Developers must pass all the same required fields just as if they were sending a dedicated POST request for that object. Here's a sample JSON payload with two new external objects inside a new Person object (a new Contact, which in turn contains a new ContactType):
{
"LastName": "McCoy",
"FirstName": "Leonard",
"ReportingAuthority": "USSEnterprise",
"Contacts": [{
"Contact": {
"ReportingAuthority": "USSEnterprise",
"ModuleCode": "ENT-CV",
"ContactValue": "X-109-7Z",
"ContactType": {
"ReportingAuthority": "USSEnterprise",
"ModuleCode": "ENT-CM",
"Type": "Communicator",
"Code": "COMM"
}
}
}]
}
WARNING: New external objects are processed innermost leaves first, top to bottom. Errors will be returned immediately before subsequent objects are processed.
Module Attachments
Module objects can accept and store attachment files in a wide variety of formats: Microsoft Word or Excel, CSV, JPEG, text, et cetera. Attachments can be accessed through the object sub-resource files. This resource supports retrieval or deletion of existing file attachments and the upload of new file attachments.
The verbs GET, POST, and DELETE are supported when working with attachments. Updating an existing attachment (PUT) is not supported at this time.
Verbs for Attachments
GET attachment
Attachments can be downloading using the hypermedia URL embedded in the files resource response.
Path:
/subscribers/{subscriber}/modules/{module}/{identifier}/files/{attachmentKey}
Request Headers:
Accept: application/octet-stream
Accept: application/pdf
Authorization: Basic [username:password Base64 encoded]
DWaySessionId: Session key from previous authentication, if available
If-None-Match: [ETag value from previous request. Only available for object GETs]
Response Headers:
Content-Type: application/octet-stream
DWaySessionId: Session key from previous authentication, if available
ETag: [ETag value]
Status Codes:
HTTP 200: Success
HTTP 304: No change
HTTP 404: Not Found (object ID cannot be resolved)
HTTP 415: Unsupported media type. File could not be converted to PDF.
HTTP 500: Server-side error (see response body)
Sample URL:
https://server/rest/v2/subscribers/ERTSE35233/modules/DWFND-PER/PER%202011-1234/file/MDAxYy5jc3Y6MjQxMg
Sample Request Body:
Request body is unused for this activity.
Sample Response:
Response is an octet-stream. Additional file information is in the following header values and depends on the attachment being retrieved:
Content-disposition: attachment; filename
Content-Type: ...
Content-Length: ...
GET attachments
Retrieve a list of attachments associated with an object identifier. The response document contains hypermedia links to the attachment data. Use these URLs in lieu of constructing URLs in your application.
Path:
/subscribers/{subscriber}/modules/{module}/{identifier}/files
Request Headers:
Accept: application/json*
Authorization: Basic [username:password Base64 encoded]
DWaySessionId: Session key from previous authentication, if available
If-None-Match: [ETag value from previous request. Only available for object GETs]
* XML responses are not supported for this feature
Response Headers:
Content-Type: application/json*
DWaySessionId: Session key from previous authentication, if available
ETag: [ETag value]
Status Codes:
HTTP 200: Success
HTTP 304: No change
HTTP 404: Not Found (object ID cannot be resolved)
HTTP 500: Server-side error (see response body)
Sample URL:
https://server/rest/v2/subscribers/ERTSE35233/modules/DWFND-PER/PER%202011-1234/files/
Sample Request Body:
Request body is unused for this activity.
Sample JSON Response:
[
{
"fileName": "001c.csv",
"creationDate": "2013-01-21T22:42:31.000 PST",
"excludeFromPrint": "N",
"link": {
"rel": "self",
"type": "application/csv",
"href": "http://server/rest/v2/subscribers/QUHKTT3671/modules/RF-TRS/TRS%202012-0013/files/MDAxYy5jc3Y6MjQxMg"
}
},
{
"fileName": "image.png",
"creationDate": "2013-02-01T14:59:15.000 PST",
"excludeFromPrint": "N",
"link": {
"rel": "self",
"type": "image/png",
"href": "http://server/rest/v2/subscribers/QUHKTT3671/modules/RF-TRS/TRS%202012-0013/files/aW1hZ2UucG5nOjI1NDY"
}
},
{
"fileName": "Solution_Profile_1.xlsx",
"creationDate": "2013-02-01T16:20:57.000 PST",
"excludeFromPrint": "Y",
"link": {
"rel": "self",
"type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
"href": "http://server/rest/v2/subscribers/QUHKTT3671/modules/RF-TRS/TRS%202012-0013/files/WGNlbF9Tb2x1dGlvbl9"
}
}
]
POST attachment
Attachments can be uploaded using the files resource.
Path:
/subscribers/{subscriber}/modules/{module}/{identifier}/files/
Request Headers:
Content-Type: multipart/form-data
Authorization: Basic [username:password Base64 encoded]
DWaySessionId: Session key from previous authentication, if available
Status Codes:
HTTP 201: Created (successful response)
HTTP 500: Server-side error (see response body)
Sample URL:
https://server/rest/v2/subscribers/ERTSE35233/modules/DWFND-PER/PER%202011-1234/files
Sample Request Body:
Form parameter file.
Form parameter excludePrint : true / false. Should this attachment be excluded from prints. Default value is false.
Sample Response:
Response body is unused for this activity. See the Location header in the response for the new attachment URL, for example:
Location: http://server/rest/v2/subscribers/QUHKTT3671/modules/RF-TRS/TRS%202012-0013/files/aW1hZ2VfcG9zdF8yLnBuZzoyNTYy
PUT attachment
Attachments can be modified using the files resource. Use the hypermedia URLs found in the GET response. The 'Files Modifiable' attribute needs to be enabled for the Attachments grid in the Module definition.
Path:
/subscribers/{subscriber}/modules/{module}/{identifier}/files/{attachmentKey}
Request Headers:
Content-Type: multipart/form-data
Authorization: Basic [username:password Base64 encoded]
DWaySessionId: Session key from previous authentication, if available
Status Codes:
HTTP 200: Success
HTTP 403: Forbidden ('Object is missing attribute MODIFIABLE', when the 'Files Modifiable' attribute is not enabled for the module's Attachments grid)
HTTP 500: Server-side error (see response body)
Sample URL:
https://server/rest/v2/subscribers/ERTSE35233/modules/DWFND-PER/PER%202011-1234/files/aW1hZ2VfcG9zdF8yLnBuZzoyNTYy
Sample Request Body:
Form parameter file.
Form parameter excludePrint : true / false. Should this attachment be excluded from prints. Default value is false.
Sample Response:
Response body is unused for this activity. See the Location header in the response for the new attachment URL, for example:
Location: http://server/rest/v2/subscribers/QUHKTT3671/modules/RF-TRS/TRS%202012-0013/files/aW1hZ2VfcG9zdF8yLnBuZzoyNTYy
DELETE attachment
Attachments can be deleted using the files resource. Use the hypermedia URLs found in the GET response.
Path:
/subscribers/{subscriber}/modules/{module}/{identifier}/files/{attachmentKey}
Request Headers:
Authorization: Basic [username:password Base64 encoded]
DWaySessionId: Session key from previous authentication, if available
Status Codes:
HTTP 204: Success, No Content
HTTP 404: Not Found (object identifier or attachment key cannot be resolved)
HTTP 500: Server-side error (see response body)
Sample URL:
https://server/rest/v2/subscribers/ERTSE35233/modules/DWFND-PER/PER%202011-1234/files/MDAxYy5jc3Y6MjQxMg
Sample Request Body:
Request body is unused for this activity.
Sample Response:
Response body is unused for this activity.
Subscriber Resource
Clients can access information about a subscriber at this resource. Embedded in this resource are two optional values 'person_module' and 'person_object'. These are values that will populate if you have a "Persons" module defined in Preferences screen under the 'Person and Teams' heading.
Sample URL:
https://server/rest/v2/subscribers/ERTSE35233
Sample JSON Response:
{
"preferences": {
"companyCode": "RF",
"areaName": "DWAYDev",
"dateFormat": "YYYY-MM-DD",
"timeZoneCode": "EST",
"companyName": "Rodeo Frog",
"areaDesc": "Dev",
"areaType": "DEV",
"helpUrl": "https://docs.devonway.com/docs/common",
"sessionTimeout": "120",
"required": "asterisk",
"keepAliveTimer": "2",
"areaSubCode": "DWAY"
},
"person_module": "RF-PRSN",
"person_object": {
"PersonName": "Smith, Joe",
"InitiatorSDepartment": "",
"AnyChild": "10000",
"Anything": "",
"FirstName": "Joe",
"InitiatedBy": "Fitzwalter, Luke",
"AnyTitle": "",
"InitiatedOn": "2014-11-05T20:25:00Z",
"Identifier": "PRSN 2014-0001",
"Counter": "2",
"PersonID": {
"PersonId": "2004000720",
"Name": "Smith, Joe"
},
"Number": "",
"Remarks": [],
"WorkStatus": "Active",
"FullName": "Smith, Joe",
"LastName": "Smith",
"ReportingAuthority": "Rodeo Frog",
"BirthDate": "1986-01-01T06:00:00Z"
},
"person": {
"firstName": "Joe",
"lastName": "Smith",
"_id": "dwaydev_quhktt3671_2004000720"
},
"broadcastMessages": [{
"text": "Update 6/20/2020. This area is now running on the software platform YourWay 2.48",
"ludt": "20200320204118000"
}]
}
Search Resource
A users previously saved searches can be access and run from this resource. All of the search criteria is defined by the user from the UI. The availability of these searches depends on the user-specific access. Results are paginated in blocks of 10 results. Each response includes a totalResults integer that describes the total number of results the search returned. The integer resultsPosition describes the starting position of the current results within the totalResults value. To navigate the paginated search results, use the url parameter ?page and increment it by 1.
Sample URL:
https://server/rest/v2/subscribers/ERTSE35233/search
Sample JSON Response for list of saved searches:
[
{
"name": "Tasks to complete",
"href": "https://server/rest/v2/subscribers/ERTSE35233/search/2004000720-1"
},
{
"name": "Tasks to approve",
"href": "https://server/rest/v2/subscribers/ERTSE35233/search/2004000720-2"
}
]
Sample URL:
https://server/rest/v2/subscribers/ERTSE35233/search/2004000720-10
https://server/rest/v2/subscribers/ERTSE35233/search/2004000720-10?page=1
Sample JSON Response from dataset:
{
"totalResults": 2,
"resultsPosition": 0,
"results" :
[
{
"LastUpdatedOn": "2013-09-13 19:38:35.97",
"ObjectStatus": "Open",
"YearRecorded": "2009",
"ReportingAuthorityCode": "RF",
"Title": "Review engineering document ED-2013-0001",
"ObjectType": "Regular",
"ObjectID": 43671,
"CreatedOn": "2013-09-13 14:38:22.877",
"_PrimaryObjectID": "43671",
"_PrimaryID": "43671",
"Identifier": "LP 2013-0009"
},
{
"LastUpdatedOn": "2013-09-13 20:34:27.36",
"ObjectStatus": "Open",
"YearRecorded": "2009",
"ReportingAuthorityCode": "RF",
"Title": "Review engineering document ED-2013-0002",
"ObjectType": "Regular",
"ObjectID": 43672,
"CreatedOn": "2013-09-13 15:34:26.4",
"_PrimaryObjectID": "43672",
"_PrimaryID": "43672",
"Identifier": "LP 2013-0010"
}
]
}
Sample JSON Response from module search:
{
"totalResults": 2,
"resultsPosition": 0,
"results" :
[
{
"ON": "20120515T1310 MDT",
"RA": "Rodeo Frog",
"ID": "LP 2012-0001"
},
{
"ON": "20120515T1145 MDT",
"RA": "Rodeo Frog",
"ID": "LP 2012-0002"
}
]
}
Print Resource
Users can generate pdf representations of an object using the print resource. This resource mirrors the print functionality available to users in the application. In cases where long running pdf generation is expect we recommend you use the async option.
Request Headers:
Authorization: Basic [username:password Base64 encoded]
DWaySessionId: Session key from previous authentication, if available
Status Codes:
HTTP 200: Status response code when successfully downloading a pdf.
HTTP 202: Status response code when an async print job is polled for status and hasn't finished processing.
HTTP 303: A successfully completed print will return this code and location to the pdf. Async prints will return a job url that can be polled for status. Successfully completed job urls will return a location to the pdf.
HTTP 403: Insufficient Access for identifier.
HTTP 404: Not Found (object identifier or attachment key cannot be resolved)
HTTP 410: When an async print job key is invalid or has expired and been purged from the system.
HTTP 500: Server-side error (see response body)
Sample Request Body:
Request body is unused for this activity.
Sample Response:
Response body is unused for this activity.
Response Header:
Location: This header will contain a url to the Pdf file or async print job url.
Print URL Path:
https://server/rest/v2/subscribers/{subscriber}/modules/{moduleCode}/{identifier}/print/{printCode}
GET Print:
https://server/rest/v2/subscribers/ERTSE35233/modules/RF-PRNT/PRNT%202014-0009/print/RF-PRNT-O-2
GET Asynchronous print
https://server/rest/v2/subscribers/ERTSE35233/modules/RF-PRNT/PRNT%202014-0009/print/RF-PRNT-O-2?async=true
GET Asynchronous print job
https://server/rest/v2/subscribers/ERTSE35233/modules/RF-PRNT/PRNT%202014-0009/print/job/NDUxMjh8MzRlNDlmMGMtZmU2My00MjEzLWIwNDMtMzlhMjY5ZTJiZThkfDIwMTQwNTAxMTMwNTA5NDI0
GET Print code options
https://server/rest/v2/subscribers/ERTSE35233/modules/RF-PRNT/PRNT%202014-0009/print/
Sample JSON Response from Print Code Options:
[
{
"isDefault": "N",
"name": "Archive",
"code": "RF-PRNT-O-1"
},
{
"isDefault": "Y",
"name": "Default",
"code": "RF-PRNT-O-2"
}
]
References
- REST article on Wikipedia: http://en.wikipedia.org/wiki/Representational_state_transfer
- RFC2616 Hypertext Transfer Protocol -- HTTP/1.1: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html
- RFC2617 HTTP Authentication: Basic and Digest Access Authentication: http://tools.ietf.org/html/rfc2617
- URL "percent" encoding: http://en.wikipedia.org/wiki/Percent-encoding
- JSON format reference: http://www.json.org/