Skip to main content

HTTP Reference

This reference guide covers HTTP methods, headers, and server configuration for working with the Digital.ai Agility API.

HTTP Methods​

The Digital.ai Agility API supports standard HTTP methods for retrieving and manipulating data.

HTTP GET​

HTTP GET is used to retrieve data from the Agility API. GET requests should not modify server state.

Specification: W3C HTTP GET Specification

Characteristics:

  • Idempotent (multiple identical requests have the same effect as a single request)
  • Cacheable
  • Parameters passed in URL query string
  • Safe method (does not modify resources)

Common Uses:

  • Querying assets
  • Retrieving metadata
  • Fetching attribute values
  • Getting relationship data

HTTP POST​

HTTP POST is used to create new assets or execute operations in the Agility API.

Specification: W3C HTTP POST Specification

Characteristics:

  • Not idempotent (multiple requests may create multiple resources)
  • Not cacheable
  • Request payload in message body
  • Can modify server state

Common Uses:

  • Creating new assets
  • Updating asset attributes
  • Executing operations
  • Deleting assets

HTTP Headers​

User-Agent Header​

In general, a User-Agent header identifies the client software originating an HTTP request, even when the client is not operated by a user. Browsers usually set the User-Agent header automatically. Even if you are writing your own code, the HTTP library you use will probably send an automatic User-Agent header.

For Digital.ai Agility, it can be helpful to system administrators if your own code is uniquely identified by the User-Agent header. Agility monitors the HTTP logs for hosted customers so a unique User-Agent string helps with pro-active monitoring and troubleshooting.

The HTTP specification for the User-Agent header leaves a lot of room for variation. Agility recommends you override the default User-Agent header in an HTTP request made from your own application. You should construct the User-Agent string by appending your product's name and version to the name and version of the HTTP libraries you use.

Example using curl:

curl --user-agent "`curl -V|head -n 1` StoryReport/1.0" -u remote:remote https://www14.v1host.com/v1sdktesting/rest-1.v1/Data/Story?page=10,0

This will generate a header that resembles the following:

User-Agent: curl 7.30.0 (i386-pc-win32) libcurl/7.30.0 OpenSSL/0.9.8y zlib/1.2.7 StoryReport/1.0

Standard Request Headers​

A request header is an HTTP header that can be used in an HTTP request to provide information about the request context, so that the server can tailor the response.

Common Request Headers Used with Agility API:

HeaderPurposeExample
AuthorizationAuthentication credentialsBearer YOUR_TOKEN
Content-TypeFormat of request bodyapplication/json
AcceptPreferred response formatapplication/json
User-AgentClient identificationMyApp/1.0

Server Base URI​

The VersionOne application is a web application. It contains many resources accessible by URLs. The server base URI is common to all the resource URLs. By convention, the server base URI does not have a trailing slash.

Determining Your Server Base URI​

From the login URL, remove "/Account.mvc/Login". From My Home → Getting Started, remove "/Default.aspx" and everything that follows.

Examples:

Full URLServer Base URI
https://www14.v1host.com/v1sdktesting/Account.mvc/LogInhttps://www14.v1host.com/v1sdktesting
http://versionone.example.com/Default.aspx?menu=MyHomeEnterpriseGettingStartedPage&feat-nav=-m1http://versionone.example.com

Using Server Base URI​

Once you have identified your server base URI, you can construct API endpoint URLs by appending the endpoint path:

Examples:

  • <Server Base URI>/rest-1.v1/Data/Story
  • <Server Base URI>/meta.v1/Story
  • <Server Base URI>/query.v1

Best Practices​

HTTP Method Selection​

  • Use GET for read-only operations
  • Use POST for creating, updating, or deleting resources
  • Never use GET for operations that modify data

Header Configuration​

  • Always set a meaningful User-Agent header for custom applications
  • Use Content-Type: application/json for JSON payloads
  • Use Content-Type: text/xml for XML payloads
  • Include authentication headers in every request

Error Handling​

  • Check HTTP status codes before processing response
  • Handle 4xx errors (client errors) differently from 5xx errors (server errors)
  • Implement retry logic for 5xx errors with exponential backoff
  • See HTTP Error Codes for detailed error information