📗

All Octopus API requests are JSON objects. With the exception of the authentication and system information methods, all share a common structure.

The example below shows a simple request to the AbEntryRead method. It serves to illustrate some of the features common to all Octopus API requests that are discussed below.

For more examples, please use our public Postman collections.

Basic Request Syntax

Token

With the exception of the Authenticate and GetSystemInfo methods, all Octopus API methods require that a valid token be passed in the request. If no token is supplied, the request will fail with an error.

Authentication token passed as a header:

Authorization: Bearer dwpfefpz8vk99afp7j0s
POST 
{
  "AbEntry":{
    "Data":{
      "Key": 1,
    }
  }
}

Entity

Aside from the Token, the other top-level object in most requests is the entity being passed in the request. In the example below, since this is an AbEntryRead request, the entity that is passed is an AbEntry entity.

The contents of the AbEntry entity object will vary depending on the method being called. For information about how to construct the specific requests for each method, see the Entity Access Methods section.

The authentication and system information methods do not follow this basic structure, as they do not require an entity object to be supplied. The request structure for these methods varies depending on the method. See the Authentication Methods section and System Methods section for details about the requests for these methods.

AbEntryRead Request Example

{
  "AbEntry":{
    "Scope":{
      "Fields":{
        "Key":1,
        "CompanyName":1
      }
    },
    "Criteria":{
      "SearchQuery":{
        "$LIKE":{
          "CompanyName":"A%"
        }
      }
    },
    "Options":{}
  }
}

AbEntryCreate Request Example

{
  "AbEntry":{
    "Data":{
      "Key":null,
      "Type":"Company",
      "CompanyName":"ABC Wine Shop"
    }
  }
}

AbEntryUpdate Request Example

{
  "AbEntry":{
    "Data":{
      "Key":"Q29udGFjdAkwMDEwMDIwMDA2MTMwNjM2NzExNTZDCTc=",
      "CompanyName":"ABC Wine Shop"
    }
  }
}

AbEntryDelete Request Example

{
  "AbEntry":{
    "Data":{
      "Key":"Q29udGFjdAkwMDEwMDIwMDA2MTMwNjM2NzExNTZDCTg="
    }
  }
}

Basic Response Syntax

Code

All Octopus API methods return an integer Code to indicate if the request was successful or if it failed.

A Code value of 0 indicates that the request was successful. A negative Code value indicates that an error occurred when processing the request.

Data

If the request is successful, all Octopus API methods return a Data object which contains the results of the request.

For entity methods, the Data object is nested inside the root level entity object corresponding to the method being called.

The contents of the Data object vary depending on the method being called.

Msg

The Msg property, if present is an array of strings that contain additional informaiton about the request or the response.

For example, the Msg property may contain information about errors or request failures, or about the status of the API itself.

• If the request fails for any reason, all Octopus API methods return a Msg array containing information about the error that has occurred to help with troubleshooting.
• If the entity or method that is called is still in a beta or testing release state, the Msg array will contain a message indicating that the method should not be used in a production environment.

Example (Authenticate Success)

{
  "Code":0,
  "Data":{
    "Token":"bxqt7aofkbf0tts2bxgs"
  }
}

Example (AbEntryRead Success)

{
  "Code":0,
  "AbEntry":{
    "Data":[
      {
        "Key":"Q29udGFjdAkwMDEwMDIwMDA2MTMwNjM2NzExNTZDCTU=",
        "CompanyName":"ABC Wine Shop"
      },
      {
        "Key":"Q29udGFjdAkzNzI2NjIwMDA3MQkx",
        "CompanyName":"Ansley Wine Merchants"
      }
    ]
  }
}

Example (Error)

{
  "Code":-1,
  "Msg":[
    "The given key is of a type not supported by the target object.(DONOTUPDATE)"
  ]
}