AODocs APIs are the HTTP endpoints which let you issue direct requests to the resource server to perform many of the manual tasks done in the AODocs UI:
Most of the tasks (and more) that can be achieved from the AODocs UI can also be performed using the API.
The purpose of Drive APIs is to upload, read, alter, copy, and download Drive files and their content — use them to put into place and manage Drive files before and after attaching them to AODocs documents. Only Drive APIs can be used for this purpose, and the AODocs API does not provide any way to interact with the content of the Drive files directly.
⭑ Note: You can use any available version of Google Drive APIs (v2 or v3).
To attach Drive files to AODocs documents in SF and DMS libraries you have to use both Drive and AODocs APIs together because they need to work in tandem to connect the two worlds.
⭑ Note: Files created in a TF library’s folder will create AODocs documents automatically.
Once attached, you can do most things you need with only AODocs APIs: you will still use Drive APIs to perform any tasks related to the content of the attachments like reading, copying, and downloading Drive files; but you will use AODocs APIs exclusively for all tasks related to the AODocs documents wrapped around the Drive files, such as managing and configuring AODocs metadata, roles, and workflows.
Some of the concrete tasks you can perform with the AODocs APIs:
To manage folders and edit permissions, you have to use either Drive or AODocs APIs, depending on the library type and which storage account owns the resource: Drive APIs for TF; AODocs APIs for DMS and SF.
To manage and configure AODocs documents, you can use only AODocs APIs.
AODocs APIs are designed around principles of REST : to interact with them, you ask the server to use HTTP operations to perform read and write actions on a specified resource, as well as by providing certain parameters to configure the request. You then parse the responses that come back. You can do this using the following methods:
The AODocs API shares a lot of similarities in its design with the Google APIs, so if you’re familiar with the various G Suite APIs (Drive, Calendar, GMail) you should be able to understand the AODocs API principles very quickly.
On a high level, the interaction consists of three stages:
You send a request containing the following information to the API server:
? in the URL, mandatory)
? in the URL, usually optional)
To access AODocs APIs, you must use the following base URL:
https://aodocs.altirnao.com/api/
⭑ Note: This URL is used to build interactions with AODocs API resources but yields no useful results on its own.
Different parts of the request naturally lend themselves to carrying certain kinds of parameters, or at least are used that way customarily.
There are generally three ways you can send parameters inside a request:
GET /library/v1/abcd12345?include=NONE)GET /library/v1?documentId=abcd12345){“documentId”: “abcd12345”})Authorization: Bearer <token>)Specific variable parts of the endpoint URL (like AODocs /documentType/v1/typeId or /library/v1/libraryId APIs) are considered path parameters. These parameters get provided in the part of the URL after the host name and before the ?, and this is where the server expects to find them.
Search filters, security codes, and other query parameters are commonly strung into a key-value list in the part of the URL after the ?. The resource server has built-in mechanisms to parse this information.
💡 Tip: The following query parameters exist globally across AODocs APIs:
- domain
- security code (authentication mechanism)
- fields query parameter (to filter results and improve performance)
REST-oriented APIs such as AODocs model their objects (such as documents, classes, or libraries) as a hierarchy of directly addressable resources, or addressable collections of information or metadata.
A resource type (such as ApiDocument) is the schema that outlines how a resource can be represented. A representation of a resource is the (in our case JSON-formatted) instance of the schema above. This JSON-formatted instance is a representation of a resource, but is often simply called resource.
You send the (usually partial) resource to the server as a request body, along with a request to perform an HTTP-verb operation like GET or PATCH. Once the server performs the requested operation, it sends back the (usually complete) resource to the client as a response body.
API resources (like a Document or Library) that you want to create or update must be sent as part of the request resource, in the request body.
They are returned as the response body when a request is successful. Usually, the format of an API resource is the same in the request body and the response body.
⭑ Note: You can get a partial resource back if you filter the response fields using the
fieldsparameter.
Read more about AODocs resources.
PUT https://aodocs.altirnao.com/api/document/v1
Authorization: Bearer [YOUR_ACCESS_TOKEN]
{
"libraryId":"RnTG8PD8u8ZqTuDVHcv",
"classId":"RnTf1mx835gaTJLzoFp",
"title":"My Important AODocs Document"
}
The resource server hosts and performs operations on a requested resource (such as a library), subresources (such as a library’s permissions), or a collection of resources (such as a list of libraries).
If the resource server accepts your request, it then does the following:
DELETE)For example, the server might apply a GET request to an ApiLibraryList resource/collection and return the resource/collection to the requesting party.
The server either succeeds in fulfilling the request, or something goes wrong. The latter case is uncommon, but when it does occur, many things can be the culprit.
If the server succeeds in fulfilling the request, it responds with a 200-series status code (usually 200 OK) and a response body which is a full or filtered JSON representation of the resource the server operated on. Each resource type returned as part of a successful response has a different structure (“schema”): you can look up the schema for each such resource type in the reference, such as ApiDocument.
⭑ Note: If the requested operation is
DELETE, the server sends back204 OKandnullinstead of a representation of a resource, regardless if the resource was sent to Trash (retrievable) or deleted permanently. If you delete the document permanently, thedocumentIdstops being recognized from that point on. If you send the document to Trash, the document ID persists.
If there was something wrong with the request or with the server’s ability to perform the operation, the response comes back as a status code and JSON-formatted error message to help guide your next steps.
The response provides a standard HTTP status code to indicate success (2xx), failure (4xx), or some other condition (5xx); as well as an error message to guide the next steps.
Read more in HTTP status codes in AODocs APIs to determine the type of issue and how to resolve it.
Pagination comes into play when dealing with resource collections, since the results are often longer than a single page. Read more on the Performance considerations page.
Any version marked beta indicates that the version of this API method is not final, and might be subject to sudden deprecation and removal from the API, with a better alternative provided as a replacement. However, as long as the method is live, we’ll try to ensure backward compatibility as much as possible.
APIs not marked as beta are considered “stable”: they have permanence and retain backward compatibility, unless they suffer from low usage.
Here is how you can get started working with AODocs APIs: