API Overview

The GoGoWorx Application Program Interface (API) allows programmatic access to your account's content from your applications or scripts.

This can be used for importing or exporting content, or to control access to content.

Secure Protocol

The GoGoWorx API only supports secure HTTPS connections with a minimum Transport Layer Security (TLS) version of 1.2

The TLS protocol addresses network security problems such as tampering and eavesdropping between a client and server. When applications establish a TLS handshake to the GoGoWorx API, the security policy enforces the TLS 1.2 version and cipher suite.

Your applications can use one of the following TLS Ciphers: 

The TLS version and cipher suite used is normally taken care of automatically during connection negotiation, so these details are for information purposes only.

API Certificate

The secure certificate associated with the GoGoWorx API Gateway will be signed with a valid gogoworx.com certificate. Your application should validate the certificate to confirm that it is connected to the legitimate GoGoWorx API Gateway.

Connecting to the API

The primary GoGoWorx API Gateway is located at https://api.gogoworx.com and provides access to the various endpoints to access various functionality, such as /category and /article for access to category and article functionality for example.

You should only use this API Gateway if you have a valid API Key and GoGoWorx account.

Endpoints

There are various endpoints available in our API Gateway that provide access to different functionality as described below:

• /category : provides access to category objects via the Category API
• /article : provides access to article objects via the Article API
• /group : provides access to group objects via the Group API
• /user : provides access to user objects via the User API
• /category_group : provides access to category_group objects via the Category Group API
• /user_group : provides access to user_group objects via the User Group API
• /search : provides access to search functionality via the Search API

API Methods

The GoGoWorx API Gateway is implemented with a RESTful interface, allowing a wide range of applications and services to interact with it seamlessly, using a large array of languages and technology stacks.

Methods are used to determine the type of operation being performed by each request as described in the table below

A combination of these methods can be assigned to any of the defined API Keys. Note that some of these methods may not be available in every endpoint implementation. Read the API documentation for each endpoint for details.

Account UUID

API requests require a unique account identifier, which is accessible to account admins through the dashboard API Keys page.

This automatically generated unique identifier is a UUID that will look something like this : 02fccd86-18e8-4816-a52c-bd3bf9f8446e

See the API Authentication section below for details on how to use this when making API requests.

API Keys

Your GoGoWorx account administrator will be able to create and configure up to 10 API Keys for your account through the dashboard API Keys page.

Each API Key has a unique identifier associated with it, which looks something like this : qI9CSNml2mwL7zPVpwLW4WBJPCmTcIkBKeCQL1t7

Also, every API Key controls which specific API Endpoints can be accessed and also which methods within that endpoint are enabled.

For example, an API Key might provide only GET access to the /category and /article endpoints, while another API Key (given to more privileged applications or users) might have full (GET, POST, PUT, DELETE) access to those same endpoints. The configuration of which keys can access which methods in which API endpoints is determined by your admin users.

API Authentication

In order to confirm requests processed in our API Gateway are legitimate and for the appropriate account, a combined set of verifications is in place for accessing every API endpoint.

Specifically, for a request to work, it requires a valid account UUID, the account's site name as well as a valid API Key that has been configured for that account.

Only when all three of these factors have been authenticated will the request be processed.

We have implemented an easy mechanism to use these different authentication factors using HTTP Headers that accompany each request, as shown below.

curl -X GET https://api.gogoworx.com/group \
    -H "x-api-key: qI9CSNml2mwL7zPVpwLW4WBJPCmTcIkBKeCQL1t7" \
    -H "x-account-uuid: sitename/02fccd86-18e8-4816-a52c-bd3bf9f8446e" \
    -d '{"public_access": "true", "limit": 20}'

Example response from the above request:

[{
	"group_id": 42,
	"name": "Public Access",
	"description": "Articles and categories that can be viewed without requiring user registration",
	"public_access": true
},
{
	"group_id": 43,
	"name": "Public Access 2",
	"description": "Another public group",
	"public_access": true
}]

If you look closely at the request being sent, there are two headers specified with the -H option. Let's look at both of these in turn

API Key Header

The API Header is used to specify the API Key you would like to use for the request. In the example above, the API Used is qI9CSNml2mwL7zPVpwLW4WBJPCmTcIkBKeCQL1t7 (an invalid example).

The name of the header containing this value is called x-api-key and should be in the format shown in the example, with the header name ( x-api-key ) followed by a colon, followed by the API Key value, as shown here:

Account UUID Header

The Account UUID Header is to identify which account is being accessed. Account admins are able to obtain the unique UUID associated with the account by accessing the API Keys page from the main application dashboard.

In the above example, the Account UUID used was 02fccd86-18e8-4816-a52c-bd3bf9f8446e (an invalid example)

In addition to this value, you also need to specify the unique sitename associated with your account.

The name of the header containing this value is called x-account-uuid and should be in the format shown in the example above with the header name ( x-account-uuid ) followed by a colon, followed by a combination of sitename + / + account_uuid as shown here:

Testing Your Connectivity

To confirm your connectivity when working with the GoGoWorx API Gateway functions, select a simple request to verify that your authentication and request parameters are correct.

In the various examples we have included, many show how to make calls using the common command line tool curl, so one simple method of testing may be to use that to make sure that your authentication strings and API Keys are configured correctly before you attempt making calls from your own applications.

Here is a simple example that should yield a result, assuming you have at least one category defined in your account. Note that you can specify an additional -v parameter to provide additional verbosity in the output sent to your console, which might be helpful in debugging any issues.

curl -i -X GET https://api.gogoworx.com/category \
    -H "x-api-key: qI9CSNml2mwL7zPVpwLW4WBJPCmTcIkBKeCQL1t7" \
    -H "x-account-uuid: sitename/02fccd86-18e8-4816-a52c-bd3bf9f8446e" \
    -d '{"parent_id": 0, "limit": 1}'

Which should return at least one category object as shown here (your object values will likely differ):

[{
    "category_id": 123,
    "parent_id": 0,
    "category_name": "My Category",
    "slug": "my-category",
    "published": true,
    "modified_date": 1588698334,
    "icon_id": 1
}]

A valid response will return a JSON object inline (in the above example, we have formatted this to be more readable).

API Message Quota

Each account that has API Access enabled, has by default up to 50,000 requests per month included in the account plan. Using more than this amount carries some overhead for our systems, so an additional small fee is applied to your account when the number of calls exceeds this amount in any given month, using this simple formula:

First 50,000 API Calls per month:  included in plan pricing

Each additional 100,000 API Calls per month (above the initial 50,000) will be charged at $3.50 per 100,000 requests.

For example, making 320,000 calls in a single month would be  3 x $3.50  =  $10.50, which will be automatically billed to your account.

Contact us for details of special rates if you plan to use more than the above amount of API messages. For normal usage, 50,000 API requests per month is far more than most users will need, and the additional expense of exceeding this limit occasionally is not significant. Our goal is to enable this API functional, not limit it.

Related Articles

1		Article API Endpoint
2		Category API Endpoint
3		User API Endpoint
4		Group API Endpoint
5		Search API Endpoint
6		Testing API Connectivity