Understanding Integration Terms and Troubleshooting Status Codes

Written by Jim Le Updated over a week ago

If you’re new to API Integrations, you’ll want to briefly review the following terminology in order to help you integrate various third party applications to your Centercode implementation. Note that technical documentation can be found at welcome.centercode.com/api.

General Integration Vocabulary

APIStands for Application Programming Interface. Enables different systems to interact with each other programmatically.

Authorization KeyAccess to API endpoints may require identity verification through an authorization key that is included in your URL or headers when making a request.

Basic AuthenticationThis encodes a username and password into base64 and adds to the header of API requests (see Header example) allowing your API request to access login credentials with every use.

EndpointAn Endpoint is a system or application that’s the target of integration. Jira, Slack, Salesforce, and even Centercode are examples of endpoints which receive and process requests.

Endpoint URLEndpoints typically indicate where/how you access their resources. One system reaches out to another by targeting the endpoint URL - an endpoint URL is essential to connect systems via API.

HeadersHeaders allow you to define additional static values sent with each request. Not all API calls require headers to be defined. A common uses for headers it to provide authorization for your Webhook by adding your access key to your header and specify how you want returned values to be formatted.

Authorization Header Example:Authorization: 2nt6cs2EyDmZ5fhNNV6cvAIP

Return value formatting example:Content-Type: application/json

JSONJavaScript Object Notation is a lightweight data-interchange format, meaning this is the language you may send and receive data from systems. Below is an example of JSON formatting.

Key

Keys are often required when creating any integration resource. The Key can be a short, descriptive entry to separate your integration from other functions that use the same Community API key for easier use. Another way to consider Keys is as a “friendly identifier”.

Key Value PairsDifferent than the “Key” above, Key Value Pairs (also known as Parameters) are a set of two linked data items: a key, which is a unique identifier for some item of data, and the value, which is either the data that is identified or a pointer to the location of that data.

Web Methods

Web Methods define a set of request methods to indicate the desired action to be performed for a given resource, also known as HTTP request methods. When creating Webhooks within your Centercode implementation, you’ll be selecting from the below Web Methods to accomplish your goals. External Listeners, Record Lookups, and Data Returns will select the appropriate Web Method for you.

GETGET requests retrieve data from an external system and enters it within your Centercode implementation to be stored and/or take action upon (through various platforms).

POSTPOST requests send data from your Centercode implementation to create or update a resource in a third-party system.

PUTPUT requests sends data from your Centercode implementation to update an existing resource in a third-party system. PUT should only be used if you’re replacing a resource in its entirety. Otherwise, you may want to consider using PATCH.

PATCHPATCH requests are to make partial update on a resource in a third-party system.

DELETEDELETE requests a resource within a third-party system to be removed.-

Centercode Integration Vocabulary

Capture Return ValuesReturn Values store responses from third party systems when your Webhook is used in order to add data to your Centercode platform, further extending your data. This allows you to use that external data anywhere via the Data Engine - as Dynamic Tags, in User and Feedback Management, Reporting, and even other integrations.

Data Group LabelThis designates the label in which your returned data is stored as to be called upon via Centercode Data Engine.

LabelLabel allows you to name the specific piece of data you’re capturing from third-party systems

ParameterParameters are how you append data to your label and call out to specific parameters of data.

Data TypeType refers to the form the data is returned as.

Boolean refers to values returned as true and false

Date and Time refers to dates and times returned

Integer basically refers to numbers to be returned

String refers to textual data returned

-

Common Status Codes for Troubleshooting

When working with API integrations, results are binary - either succeeded or failed. Below are common responses that you may see within API testing tools, your Centercode implementation, and/or your third party application.

2XX SeriesThis class of status codes indicates the action requested by the client was received, understood, accepted and processed successfully.

200 - OK - Successful request

201 - Created - Successful request, resulting in creation of a resource

202 - Accepted - The request was accepted, but not completed.

204 - No Content - The request was accepted, but the resource did not exist

4XX SeriesThe 4XX class of status code indicates the client seems to have errored out

400 - Bad Request - Request could not be understood due to misconfigured syntax

404 - Not Found - Resource not found, meaning your endpoint URL may not direct to the desired resource

405 - Wrong Method - This occurs when the improper request was attempted (e.g. POST used when PUT is more appropriate)

4XX Troubleshooting

400 - Bad RequestThis status indicates that your JSON isn’t formatted correctly in your request. Here’s an example of correct JSON formatting. Even something as small as a missing quote or comma may result in the entire request failing.

401 - UnauthorizedAccess to API endpoints may require identity verification through an authorization key or token that should be included in your URL or headers when making a request. Request received, but ensure that your authorization is correct and present in your header or URL. If tokens are used, they may have expired and may need to be replaced or refreshed.

403 - Forbidden Request and authorization received, but authorization is denied. Ensure that the account you’re using to for the integration has correct permissions to carry out your request. You may want to take a close look at your request headers and URL, then try again.

404 - Not Found Resource not found, meaning your endpoint URL may not direct to the an existing resource. Ensure that your endpoint URL directs correctly to your desired resource and try again.

405 - Wrong MethodThis occurs when the improper request was attempted (e.g. POST used when PUT is more appropriate). You’ll want to change your request method.