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.
Before You Start
Before you can make any API calls, you will need to have had your account administrator (whoever set up your GoGoWorx account perhaps) configure your system to enable API access.
To do this, they will need to visit the API Keys page of their admin dashboard and obtain the Account UUID value. Note that any used in various examples within our documentation will not be valid. Your account also needs to be active.
In addition to this, you will need the
sitename
associated with your account - the one specified in your account profile. Again, your account administrator(s) should be able to provide this.
You will also need a valid API Key that is associated with the API endpoint you are attempting to access. In the examples shown below, it uses the /category endpoint and only the GET method, so to test this, your API Key needs to be enabled with GET permission to the /category endpoint. If the API Key is only valid for other methods or other endpoints, then the requests shown below will be automatically rejected by our request Authorizer.
AP Key Cached Authorization
In order to support a huge amount of scalable traffic on our systems, our API Authorizer will cache authenticated request tokens for a period of between several minutes and up to one hour. If you are changing API Key settings, it may take some time for the Authorizer to expire the old credentials before new settings are applied.
This generally does not cause issues in production, since API Keys and their configurations are relatively static, however if you are debugging or configuring your API connectivity for the first time, you might change API Key settings frequently, so this authorization caching needs to be considered.
If you feel that your new API Key settings have not been applied to the Authorizer, there is no way to flush this through the system or invalidate the cache, which is highly automated - you may need to use an alternate or temporary API Key until the cache clears or simply wait a few minutes for the new settings to apply.
Simple Request
Here is a simple example that should yield a single result, assuming you have at least one category defined in your account.
Note that parameters can be specified either as query parameters at the end of the request URL (?parent_id=0&limit=1) or in the data (or body) of the request as shown below. The results are the same, so please feel free to use whichever method of parameter passing you are most comfortable with.
Although we support parameters being passed within query parameters or in the body (data) of the request, it is worth noting that best practice suggests placing parameters in the body instead of sending as part of the query URL itself.
One simple example of this might be when sending the content of a lengthy article. Sending this as part of your query parameters can become unwieldy, whereas sending it within the content body of the request would be the better place to include it. See this Wikipedia article on
Query Strings
for more information.
Language: bash [ Line Numbers Enabled ]
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):
Language: json [ Line Numbers Enabled ]
[{
"category_id": 123,
"parent_id": 0,
"category_name": "My Category",
"slug": "my-category",
"published": true,
"modified_date": 1588698334,
"icon_id": 1
}]
Note that the JSON object is contained within an array (as indicated by the square brackets), since there may be multiple objects returned, depending on the request parameters and results.
A valid response will return a JSON object inline (in the above example, we have formatted this to be more readable) to your console, so it may not appear as neatly as shown above, but all of the fields should be visible and looking more like this:
[{"category_id": 268, "parent_id": 0, "category_name": "Sample Content", "slug": "sample-content", "weight": 1, "published": true, "modified_date": 1590519116, "icon_id": 1}]
If you see something like this, then it indicates your authentication parameters are correct, otherwise review some of the debugging steps below and confirm you have used the correct account UUID, sitename and API Key in your headers when making the request (the examples shown above will not work).
Verbose Output
To see a more verbose output of what is being returned from the API Gateway, you can specify the -i parameter to curl in order to see the response headers, or the -v parameter to turn on more verbose output, as shown here:
Language: bash [ Line Numbers Enabled ]
curl -X GET -H "x-api-key: qI9CSNml2mwL7zPVpwLW4WBJPCmTcIkBKeCQL1t7" -H "x-account-uuid: XXXwrongXXX/02fccd86-18e8-4816-a52c-bd3bf9f8446e" 'https://api.gogoworx.com/category' -d '{"parent_id": 0, "limit": 1}' -v
* About to connect() to api.gogoworx.com port 443 (#0)
* Trying 66.66.666.64...
* Connected to api.gogoworx.com (66.666.666.64) port 443 (#0)
* Initializing NSS with certpath: sql:/etc/pki/nssdb
* CAfile: /etc/pki/tls/certs/ca-bundle.crt
CApath: none
* SSL connection using TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
* Server certificate:
* subject: CN=*.gogoworx.com
* start date: Apr 06 23:07:37 2020 GMT
* expire date: Jul 05 23:07:37 2020 GMT
* common name: *.gogoworx.com
* issuer: CN=Let's Encrypt Authority X3,O=Let's Encrypt,C=US
> GET /category HTTP/1.1
> User-Agent: curl/7.29.0
> Host: api.gogoworx.com
> Accept: */*
> x-api-key: qI9CSNml2mwL7zPVpwLW4WBJPCmTcIkBKeCQL1t7
> x-account-uuid: XXXwrongXXX/02fccd86-18e8-4816-a52c-bd3bf9f8446e
> Content-Length: 28
> Content-Type: application/x-www-form-urlencoded
>
* upload completely sent off: 28 out of 28 bytes
< HTTP/1.1 500 Internal Server Error
< Date: Fri, 29 May 2020 19:22:13 GMT
< Content-Type: application/json
< Content-Length: 16
< Connection: keep-alive
< x-amzn-RequestId: eaa9ae88-d7f5-ab12-b26a-1e7791430f4b
< x-amzn-ErrorType: AuthorizerConfigurationException
< x-amz-apigw-id: NTwT2xkbiYcFlFA=
<
* Connection #0 to host api.gogoworx.com left intact
{"message":null}
With the addition of the verbose (-v) flag in the parameters, you can see there is much more detail in the output returned.
This example is a failure case, where the sitename is purposefully incorrectly, however you will likely see something very similar if you have an incorrect or invalid API Key or Account UUID as well.
Notice the server response header indicating AuthorizerConfigurationException on line 31 above. This is a reasonably clear indication that the API Gateway's Authorizer rejected the request based on invalid values in either x-api-key or x-account-uuid request headers (or they were not present).
Line 25 indicating the status code '500 Internal Server Error' is also noteworthy. This is not an error on anything within our API Gateway processing - this is simply how authentication failures are reported back to the calling application. There are a number of different error codes that might also be reported, such as a 403 Forbidden error code if an unknown endpoint is called for example, which can happen if you have a typo in the endpoint name (
/categories
instead of
/category
for instance).
This output confirms which headers are being sent to the server as well as indicating that the server actively rejected it meaning you are able to at least connect to the API Gateway. If you don't see any response coming back from our API Gateway, it may mean that the message is not able to reach it for some reason, likely something in your system's firewall or DNS configuration settings.
DNS and Firewall Problems
If your DNS server cannot resolve the api.gogoworx.com host, you may see something like this being returned:
Language: bash [ Line Numbers Enabled ]
* Could not resolve host: api.gogoworx.com; Unknown error
* Closing connection 0
curl: (6) Could not resolve host: api.gogoworx.com; Unknown error
Your machine making the API requests also needs to be able to access the Internet, via HTTPS (TCP port 443) so firewall rules may need to be adjusted to permit this connectivity.
Double Check Parameters
In many cases, small mistakes in the specified parameters to API requests can cause frustrating problems. Please be sure to double check the values for your requests as described above.
If you continue having issues with connectivity when running curl on your system, contact our support team for assistance.
