andrewvy/project-chime-spec.md

## project-chime-spec.md

      
    Raw
  

              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:

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.

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}}


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