[WIP] Project Chime API Specification/Documentation

project-chime-spec.md

THIS IS A WORK IN PROGRESS!

Project Chime

Entity + API Specification

Here are some pieces of documentation that sets the basis for interacting with our API.

API Base URL: https://projectchime.com/api/v1

Table Of Contents

• Authentication
• Object - Users
• Object - Posts

Authentication

Project Chime uses an OAuth 2.0 implementation to authenticate access to the API.

In order to make an authorized call to the API, your application must obtain an OAuth access token on behalf of a user.

OAuth is broken into two parts:

• Obtaining an access token.
• Using the access token to authenticate requests.

The three steps of obtaining an OAuth Access Token:

1. Build an OAuth link to the Project Chime OAuth.

https://projectchime.com/oauth?
  response_type=authorization_code&
  client_id={{CLIENT_ID}}&
  redirect_uri={{REDIRECT_URI}}
  &scope={{SCOPE}}

This is a URL points to the /oauth path.

CLIENT_ID - Your Application's Client ID.
REDIRECT_URI - Your Application's OAuth Redirect URI.
SCOPE - The scope of permissions to request.

Please note that your REDIRECT_URI must be pre-registered when you configure your application.

2. Receive an authorization code and exchange it for an access token.

When the user clicks to allow the application access, it gets redirected back to the set REDIRECT_URI with an authorization code.

https://myapp.com/callback?code={{AUTHORIZATION_CODE}}

Then you can exchange this code for an access token.

POST https://projectchime.com/oauth/token?
  client_id={{CLIENT_ID}}&
  client_secret={{CLIENT_SECRET}}&
  grant_type=authorization_code&
  code={{AUTHORIZATION_CODE}}&
  redirect_uri={{REDIRECT_URI}}

3. Receive an access token.

If everything is valid and the authorization is approved by the suer, the API will send a response containing the access token to the client application.

{
  "access_token": "{{ACCESS_TOKEN}}",
  "token_type": "bearer",
  "expires_in": 2592000,
  "scope": "{{SCOPE}}",
  "info": {
    "user_id": "1230401249"
  }
}

---

[Object] Users

Users are accounts on the platform.

Fields

id - String - Unique string identifier for this User.

verified - Boolean - Whether or not this User is a "verified" account.

statuses_count - Integer/Nullable - Number of Posts this User has publicly created. This can be set to not be displayed.

following_count - Integer/Nullable - Number of Users this User is following. This can be set to not be displayed.

followers_count - Integer/Nullable - Number of followers this User has. This can be set to not be displayed.

favourites_count - Integer/Nullable - Number of posts this User has favourited.

following - Boolean/Perspectival - Indicates whether the current context User is following this User.

display_name - String - User-set displayed name.

screen_name - String - Unique screen name that the User has chosen. This can be used for mentions.

bio - String/Nullable - User-set biography.

location - String/Nullable - User-set Location.

website - String/Nullable - User-set Website URL.

---

[Object] Posts

Posts are the actual content used in Project Chime, and serve as the basis for communication.

Every post is organized into a status -> replies hierarchy.

A "status" is a root-level post, not created in relation to any other post.

A "reply" is a sub-level post anchored to either:

• a root-level status
• another reply preceding this reply

Fields

id - String - Unique string identifier for this Post.

text - String - UTF-8 content of the Post.

embeddable_text - String - HTML-formatted String of the text.

favourites_count - Integer - The number of favourites this Post has.

favourited - Boolean/Perspectival - Whether or not this Post was liked by the context of the current user requesting this Post.

nsfw - Boolean - Whether or not this Post is NSFW/SFW. (Not Safe For Work).

in_reply_to_post_id - String/Nullable - If this Post is a reply to another post, this field will contain the string ID of the parent post.

in_reply_to_user_id - String/Nullable - Nullable. If this Post is a reply, this field contains the string ID of the user that is directly mentioned in the post.

created_at - String - ISO8601 String representation of the time this Post was created.

by_user_id - String - This field contains the string ID of the author of the post.

user - User - User who is the author of this Post. See User object.

entities - Entity - List of Entity objects contained in this Post.

---

[Object] Entities

Entities are the fun meta-data objects that can be attached to a post.

These include mentions, media, hashtags, urls, and quite a bit of other things in the future!

Fields

---