The Hack Chinese

Developer API

Create a Linked App

Third-party applications that send data directly to Hack Chinese are called 'Linked Apps'.

To create a Linked App and receive a unique $app-token, email team@hackchinese.com with the following:

• App Name
• URL
• A brief description of what your app does.
• A brief description of how you plan to interact with Hack Chinese through the API.

When we receive your email, we'll contact you with next steps.

Create a Linked App and generate a unique $app-token here:

Create Linked App

Use your $app-token in every request

Include your app's unique token in the authorization header of every request:

Content-type: application/json
Authorization: $app-token

We also generate unique $user-auth-tokens for each individual student -- so your app can identify their account in Hack Chinese. These tokens are generated and displayed to students when they visit your app's sync page inside Hack Chinese:

https://www.hackchinese.com/sync-with-your-app-name

Enable students to supply your app with their unique $user-auth-token

You must create a form in your app or on your website that allows students to provide your app with their unique user token.

In your app, you should associate this token with that user, as you will need to include their $user-auth-token in every request initiated for that user.

Establish the link for each user

After a student provides your app with their unique $user-auth-token from Hack Chinese, you need to tell Hack Chinese that this link has been set up.

You can do this with a single POST to:

https://www.hackchinese.com/establish_link_for_user

Include the user's auth token in the JSON payload:

{ "user_auth_token": $user-auth-token }

Once the link has been established, we will notify the user and direct them to a set of configuration options relevant to the integration with your app.

Adding words to a user's list

To add words to a student's sync list in Hack Chinese, just POST to:

https://www.hackchinese.com/add_words_to_user_list

Include a JSON payload in the following format:

{
  "words": [
    { 
      "simplified": "咖啡",
      "pinyin": "kā fēi" 
    },
    { 
      "simplified": "北京",
      "pinyin": "běi jīng" 
    }
  ],
  "user_auth_token": $user-auth-token
}

Notes

We use pinyin to disambiguate between similar words (i.e. 行 háng and xíng).

If your request includes duplicate words, we will only add the word to that user's list once.

In the unlikely event that you send a word that is not in our database, it will be added to an approval queue to be added. The word will not show up in your student's list until we approve it's addition to our dictionary.

By default, words sent from your app will be added to a user list titled 'Your-App-Name Sync List'.

If you have multiple lists of words to send for that user, you can add a title in your JSON payload. For example:

{
  "words": [
    { 
      "simplified": "咖啡",
      "pinyin": "kā fēi" 
    },
    { 
      "simplified": "北京",
      "pinyin": "běi jīng" 
    }
  ],
  "title": "北京爱情故事 Part 3",
  "user_auth_token": $user-auth-token
}

Removing words from a user's list

To remove words to a student's sync list in Hack Chinese, just POST to:

https://www.hackchinese.com/remove_words_from_user_list

Include a JSON payload in the following format:

{
  "words": [
    { 
      "simplified": "咖啡",
      "pinyin": "kā fēi" 
    },
    { 
      "simplified": "北京",
      "pinyin": "běi jīng" 
    }
  ],
  "user_auth_token": $user-auth-token
}

By default, requests with no titles will attempt to remove words from the student's default list. If you'd like to specify which list to remove from, you can include a title (see 'add word' example above).