Voog API

URI structure

Authentication

Most API requests must have an api_token parameter that is generated for the user from the admin interface ("Account" -> "My profile"). This token ensures that all requests are made by authorized users.

The api_token should be provided using the X-API-TOKEN header:

GET /admin/api/languages/1
X-API-TOKEN: 8712f9767e6a03ab6c8a80d53fc3ef6e

Another alternative is using the url query parameter (less secure), if necessary (to test some requests in the browser, for example) by adding ?api_token=8712f9767e6a03ab6c8a80d53fc3ef6e to the end of the request URL.

Both methods work interchangeably.

Anonymous access

Some resources allows limited anonymous access (e.g. Article index etc) where API token is not required. If the endpoint allows anonymous access then it's specially marked in API documentation.

Endpoints that support anonymous access:

• Article list
• Article object
• Comments list
• Create comment
• Contents list
• Elements list
• Elements object
• Search
• Tags list
• Tags object
• Ecommerce Carts endpoints
• Ecommerce Invoice object
• Ecommerce Products list
• Ecommerce Product object
• Ecommerce Shipping methods list
• Ecommerce Shipping methods object

Request URI format

The base URI for all API requests is https://example.com/admin/api/.

The next URI segments depend on the type of request made. Most commonly, a resource id is provided within the URI itself. All other data is sent as request data.

All urls respond only to JSON requests and respond with JSON objects.

Request format

Request bodies should be in JSON format and request header have to include Content-Type header:

Content-Type: application/json

Response format

All requests respond with a JSON object. The specific format depends on the request made. For requests that modify or create a resource, a JSON representation of the resource is returned.

Errors

In case of malformed request URIs, missing resources or server-side faults, a relevant HTTP Status Code is provided in the response together with more detailed error messages in a simple JSON format.

Examples:

Unauthorized

GET /admin/api/tags/15

Status: 401 Unauthorized

{
  "message": "Unauthorized."
}

or

{
  "message": "Unauthorized. Not allowed on current subscription level."
}

Not found

GET /admin/api/tags/15

Status: 404 Not Found

{
  "message": "Not found."
}

Bad request

PUT /admin/api/tags/15

Status: 400 Bad Request

{
  "message": "It's not valid request."
}

Unprocessable Entity

PUT /admin/api/tags/15

Status: 422 Unprocessable Entity

{
  "message": "Updating of this object was unsuccessful! Please review the fields.",
  "errors": {
     "title": ["can't be blank"]
  }
}

Request Timeout

GET - /admin/api/search?q=query

Status: 408 Request Timeout

{
  "message": "Request timeout."
}

Filtering and sorting in API

API list actions support filters and sort order parameters. Read more on the API filtering page.

API clients

Ruby client

Ruby client for Voog API is provided as gem.

Install the API gem:

$ gem install voog_api

Read more about using this gem from GitHub.

NodeJS client

NodeJS wrapper for the Voog API is provided as NodeJS module.

Install the API module:

$ npm install voog.js

Read more about using this module from GitHub.