Guide

API

Using the API

Champ offers a basic API for reading the forums, topics, and posts. As of January 2020, you can also create new topics and posts.

The API expects requests to be in JSON format and will return values in JSON format.

At this time, the API is in beta testing. In other words, we don’t officially support this as a feature of Champ. However, if you notice any bugs, please do let us know and we’ll do our best to fix it. 

Note that feature requests and bugs are not the same thing. If there’s an endpoint you would like, kindly ask and we will see what we can do to accommodate.

Please also note that API usage requires knowledge in the use of REST and JSON programming. Understandably, we cannot provide assistance in your integration except for general advice that is directly related to our API usage.

Authentication

In order to use the API, all requests must be authenticated.

To get started, go to the API section in the Champ dashboard. You’ll need to generate an API secret for authentication.

Each request sent to the Champ API must have the following two headers set:

  • X-SHOPIFY-DOMAIN
  • X-API-SECRET

Set the X-SHOPIFY-DOMAIN header to be equal to your Shopify store (eg. myshop.myshopify.com).

The X-API-SECRET should correspond to the API secret that you generated in Champ’s password.

Note: Keep your API secrets safe. Never give it to a developer or anyone who you do not trust. Having your API credentials essentially give someone access to your forum database.

Each API secret you create can have its own permission level. As a result, you should scope the access to your forum appropriately and only provide access to the areas that is needed.

Authentication requests that fail will receive a 403 status from the API service.

Endpoints

All API requests should be sent to https://api.getchamp.net. Only https requests are accepted.

Three endpoints are currently available:

  • GET /forums.json
  • GET /topics.json
  • GET /topics/:id.json
  • POST /topics.json
  • GET /posts.json
  • GET /posts/:id.json
  • POST /posts.json

For :id, replace it with the id of the record to retrieve the individual record.

Topic properties

The following properties are returned for each topic object in JSON format:

PropertyCan be set via APIRequired
id
titleyesyes
statusyes
posts_count
created_at
updated_at
pinnedyes
preview_thumbnailyes
preview_descriptionyes
url
user_idyes
username
forum_idyesyes
metadatayes
errors

Special note about the metadata property: This property accepts a “hash” of key and values:

{
  forum_id: 123,
  title: "My new topic",
  metadata: {
    collection_id: 456
  }
}

You can query against this value to grab a list of topics that have a specific metadata value or posts that have a specific value using our JavaScript API.

Post properties

The following properties are returned for each post object in JSON format:

PropertyCan be set via APIRequired
id
contentyesyes
statusyes
ip
created_at
updated_at
last_edited_at
archivedyes
user_idyes
forum_idyesyes
username
topic_idyesyes
errors