├── README.md ├── 09.Third-party-API-wrappers.md ├── 03.Groups-resource.md ├── 07.Faye-endpoint.md ├── 00.Welcome.md ├── 08.Streaming-API.md ├── 01.REST-API.md ├── 02.Authentication.md ├── 06.User-resource.md ├── 04.Rooms-resource.md └── 05.Messages-resource.md /README.md: -------------------------------------------------------------------------------- 1 | Project moved to https://gitlab.com/gitlab-org/gitter/docs 2 | -------------------------------------------------------------------------------- /09.Third-party-API-wrappers.md: -------------------------------------------------------------------------------- 1 | # 3rd Party API Wrappers 2 | 3 | You can also access the Gitter API through one of the 3rd party libraries that may be more suitable to use in your language, platform, and environment. 4 | 5 | ## .NET (C#) 6 | 7 | * [Gitter#](https://github.com/Odonno/gitter-api-pcl) - provides a Gitter API interface for use in Windows (Phone) apps, .NET Framework and Xamarin platforms 8 | * [Gitter# Auth](https://github.com/Odonno/gitter-api-auth) - provides you a way to retrieve Token through OAuth2 process 9 | 10 | ## Java 11 | 12 | * [GitterJavaSDK](https://github.com/Gitteroid/GitterJavaSDK) - a Java wrapper for the Gitter API allowing synchronous, asynchronous and reactive access. 13 | 14 | ## Go 15 | 16 | * [go-gitter](https://github.com/sromku/go-gitter) - Gitter API in Go. 17 | 18 | ## PHP 19 | 20 | * [gitter-api](https://github.com/SerafimArts/gitter-api) - Gitter API implementation for php 7.0+ allowing sync, async and streaming access. 21 | 22 | ## Python 23 | 24 | * [gitterpy](https://github.com/MichaelYusko/GitterPy) - Python interface for the Gitter API 25 | -------------------------------------------------------------------------------- /03.Groups-resource.md: -------------------------------------------------------------------------------- 1 | # Groups 2 | 3 | 4 | ## Group schema 5 | 6 | - `id`: Group ID. 7 | - `name`: Group name. 8 | - `uri`: Group URI on Gitter. 9 | - `backedBy`: Security descriptor. Describes the backing object we get permissions from. 10 | - `type`: `[null|'ONE_TO_ONE'|'GH_REPO'|'GH_ORG'|'GH_USER']` 11 | - `linkPath`: Represents how we find the backing object given the type 12 | - `avatarUrl`: Base avatar URL (add `s` parameter to size) 13 | 14 | 15 | ## List Groups 16 | 17 | List groups the current user is in. 18 | 19 | ### Parameters 20 | 21 | - *none* 22 | 23 | ``` 24 | GET /v1/groups 25 | ``` 26 | 27 | Try it from the CLI: 28 | ``` 29 | 'demo api-access'; 30 | { 31 | "verb": "get", 32 | "resource": "{{api_url}}/v1/groups" 33 | } 34 | ``` 35 | 36 | ```json 37 | [ 38 | { 39 | "id": "57542c12c43b8c601976fa66", 40 | "name": "gitterHQ", 41 | "uri": "gitterHQ", 42 | "backedBy": { 43 | "type": "GH_ORG", 44 | "linkPath": "gitterHQ" 45 | }, 46 | "avatarUrl": "http://gitter.im/api/private/avatars/group/i/577ef7e4e897e2a459b1b881" 47 | }, 48 | { 49 | "id": "577faf61a7d5727908337209", 50 | "name": "i-love-cats", 51 | "uri": "i-love-cats", 52 | "backedBy": { 53 | "type": null 54 | }, 55 | "avatarUrl": "http://gitter.im/api/private/avatars/group/i/577faf61a7d5727908337209" 56 | } 57 | ] 58 | ``` 59 | 60 | ## Group sub-resources 61 | 62 | ### Rooms 63 | 64 | #### List rooms under group 65 | 66 | List of rooms nested under the specified group. 67 | 68 | ``` 69 | GET /v1/groups/:groupId/rooms 70 | ``` 71 | 72 | Try it from the CLI: 73 | ``` 74 | 'demo api-access'; 75 | { 76 | "verb": "get", 77 | "resource": "{{api_url}}/v1/groups/57542c12c43b8c601976fa66/groups" 78 | } 79 | ``` 80 | -------------------------------------------------------------------------------- /07.Faye-endpoint.md: -------------------------------------------------------------------------------- 1 | # Faye 2 | 3 | At Gitter we use Faye extensibly to publish real-time messages regarding user and room activity to all our clients. 4 | 5 | ## What is Faye? 6 | 7 | > Faye is a publish-subscribe messaging system based on the Bayeux protocol. 8 | 9 | Learn more: [Faye](http://faye.jcoglan.com/) 10 | 11 | ## Endpoints 12 | 13 | We provide Faye endpoints that look like our REST API. When a user subscribes to them, she will receive real-time activity regarding those resources: 14 | 15 | A user can subscribe to the following endpoints: 16 | 17 | - `/api/v1/user/:userId/rooms` 18 | - `/api/v1/user/:userId/rooms/:roomId/unreadItems` 19 | - `/api/v1/user/:userId` 20 | - `/api/v1/rooms/:roomId`: Room user presence. 21 | - `/api/v1/rooms/:roomId/chatMessages`: Room messages. 22 | - `/api/v1/rooms/:roomId/users`: Room users. 23 | - `/api/v1/rooms/:roomId/events`: Room events. 24 | - `/api/v1/rooms/:roomId/chatMessages/:messageId/readBy` 25 | 26 | ## Consuming messages 27 | 28 | To consume messages from Faye you'll need to use one of the provided clients. 29 | 30 | - [Gitter Realtime Client](https://github.com/gitterHQ/realtime-client) - a higher-level abstraction than a straight Faye client. 31 | - [Browser clients](http://faye.jcoglan.com/browser.html) 32 | - [Server-side Node.js clients](http://faye.jcoglan.com/node/clients.html) 33 | - [Server-side Ruby clients](http://faye.jcoglan.com/ruby/clients.html) 34 | 35 | Get the [packages](http://faye.jcoglan.com/download.html). 36 | 37 | ## Publishing messages 38 | 39 | We don't currently support publishing messages from your client to the server. For that purpose you should use our [REST API](rest-api). 40 | 41 | ## Example 42 | 43 | ### Node.js client 44 | 45 | You can find an example client at [https://github.com/gitterHQ/gitter-faye-client](https://github.com/gitterHQ/gitter-faye-client). 46 | -------------------------------------------------------------------------------- /00.Welcome.md: -------------------------------------------------------------------------------- 1 | # Welcome 2 | 3 | **Please note this is an early release of our API and should be considered to be in beta at the moment.** 4 | 5 | This is the official documentation for the Gitter API. The API documentation source is [available on GitHub](https://github.com/gitterHQ/api-docs). 6 | 7 | If you have any problems or questions, contact us at [support@gitter.im](mailto:support@gitter.im) or join the conversation at: 8 | 9 | [![Gitter](https://badges.gitter.im/gitterHQ/developers.svg)](https://gitter.im/gitterHQ/developers?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) 10 | 11 | ## Getting Started 12 | 13 | If you haven't already, please sign in. This will create a developer token, which you can easily use to test the API. Once you've signed in, you can also create Apps where you'll be provided with keys and secrets. For more information on this, please take a look at the [Authentication documentation](authentication). 14 | 15 | ## REST API 16 | 17 | Interact with rooms, users and messages in a restful way. 18 | 19 | [Documentation](rest-api) 20 | 21 | ## Streaming API 22 | 23 | A simple way to listen to messages in rooms in real-time. 24 | 25 | [Documentation](streaming-api) 26 | 27 | ## Faye 28 | 29 | Listen to detailed activity in real-time. 30 | 31 | [Documentation](faye-endpoint) 32 | 33 | ## Services 34 | 35 | The things that power your Gitter activity feed. These are open source and can be found on [GitHub](https://github.com/gitterHQ/services). 36 | 37 | [Documentation](services) 38 | 39 | ## Activity API 40 | 41 | The ability to write to the Activity feed will be coming soon in an open source format. 42 | 43 | ## 3rd Party API Wrappers 44 | 45 | There are also third party wrappers created by our awesome users, that allow you to interface with the Gitter API in a variety of environments. 46 | 47 | [List of packages](third-party-api-wrappers) 48 | -------------------------------------------------------------------------------- /08.Streaming-API.md: -------------------------------------------------------------------------------- 1 | # Streaming API 2 | 3 | **Use the streaming API to listen to messages, events and changes in rooms.** The streaming API allows real-time access to rooms. Unlike other APIs, all requests to the streaming API should be made to *stream.gitter.im*. Authentication is identical to [the REST API Authentication](authentication). 4 | 5 | ## Connecting 6 | 7 | To connect to the Streaming API, form a HTTP request and consume the resulting stream for as long as is practical. The Gitter servers will hold the connection open indefinitely (barring a server-side error, excessive client-side lag, network hiccups or routine server maintenance). If the server returns an unexpected response code, clients should wait a few seconds before trying again. 8 | 9 | ## Content Types 10 | 11 | The streaming API supports JSON stream content type. 12 | 13 | Content is encoded as UTF-8. 14 | 15 | ### JSON Stream (`application/json`) 16 | 17 | The JSON stream returns messages as JSON objects that are delimited by carriage return (`\r`). Newline characters (`\n`) may occur in messages, but carriage returns should not. 18 | 19 | Parsers must be tolerant of occasional extra newline characters placed between messages. These characters are sent as periodic "keep-alive" messages to tell clients and NAT firewalls that the connection is still alive during low message volume periods. 20 | 21 | ## Resources 22 | 23 | ``` 24 | GET /v1/rooms/:roomId/:resource 25 | ``` 26 | 27 | Available resources are: 28 | - `chatMessages` 29 | - `events` 30 | 31 | Returns rooms messages as they come in. 32 | 33 | Try it from the CLI: 34 | ``` 35 | 'demo api-access'; 36 | { 37 | "verb": "get", 38 | "resource": "{{stream_url}}/v1/rooms/:roomId/chatMessages" 39 | } 40 | ``` 41 | 42 | ## Node.js Example 43 | 44 | You can find a node example client at [https://github.com/gitterHQ/gitter-node-stream](https://github.com/gitterHQ/gitter-node-stream). 45 | 46 | ## Ruby Example 47 | 48 | You can find a ruby example client at [https://github.com/gitterHQ/gitter-ruby-stream](https://github.com/gitterHQ/gitter-ruby-stream). 49 | -------------------------------------------------------------------------------- /01.REST-API.md: -------------------------------------------------------------------------------- 1 | # REST API 2 | 3 | Use the REST API to get information about rooms and post messages. 4 | 5 | * [Authentication](authentication) 6 | * [Room resource](rooms-resource) 7 | * [Message resource](messages-resource) 8 | * [User resource](user-resource) 9 | 10 | 11 | ## HTTP Methods 12 | We try to uphold RESTful principles in the API. Listing, showing and other non-state-altering actions are done with _GET_, creating with _POST_, _PUT_ for updating and deleting with _DELETE_. 13 | 14 | ## URL Breakdown 15 | 16 | ``` 17 | https://api.gitter.im/v1/rooms/:roomId/chatMessages 18 | ``` 19 | 20 | * `https`: The Gitter API is served over secure HTTP *only*. 21 | * `v1`: API version. 22 | * `rooms`: The resource which is being requested. 23 | * `roomId`: The ID of the `Room`. 24 | * `chatMessages`: The sub-resource, a resource which is accessed in the scope of the parent resource. For example, all the messages in a room. In some cases there may be multiple sub-resources. 25 | 26 | 27 | ### Structure of an API request 28 | 29 | Example of posting a message: 30 | 31 | ``` 32 | POST /v1/rooms/:roomId/chatMessages 33 | ``` 34 | 35 | #### Headers 36 | 37 | Content-Type must be defined in the header of requests that contain data. 38 | 39 | ``` 40 | Content-Type: application/json 41 | Accept: application/json 42 | Authorization: Bearer {{token}} 43 | ``` 44 | 45 | #### Body 46 | ``` 47 | { 48 | "text":"Happy Hacking!" 49 | } 50 | ``` 51 | 52 | #### Response: 53 | 54 | ``` 55 | HTTP/1.1 200 OK 56 | Content-Type: application/json; charset=utf-8 57 | ``` 58 | ``` 59 | { 60 | "id":"5330521e20d939a3be000018", 61 | "text":"Happy Hacking!", 62 | "html":"Happy Hacking!", 63 | "sent":"2014-03-24T15:41:18.991Z", 64 | "editedAt":null, 65 | "fromUser":{ 66 | "id":"5315ef029517002db7dde53b", 67 | "username":"malditogeek", 68 | "displayName":"Mauro Pompilio", 69 | "url":"/malditogeek", 70 | "avatarUrlSmall":"https://avatars.githubusercontent.com/u/14751?", 71 | "avatarUrlMedium":"https://avatars.githubusercontent.com/u/14751?", 72 | "v":2 73 | }, 74 | "unread":false, 75 | "readBy":0, 76 | "urls":[], 77 | "mentions":[], 78 | "issues":[], 79 | "meta":{}, 80 | "v":1 81 | } 82 | ``` 83 | -------------------------------------------------------------------------------- /02.Authentication.md: -------------------------------------------------------------------------------- 1 | # Authentication 2 | 3 | ## OAuth 2.0 4 | 5 | [OAuth 2.0](http://tools.ietf.org/html/rfc6749) is an authorization framework that enables third-party applications to obtain access to Gitter on the user's behalf without getting their password. 6 | 7 | All developers need to [register their application](https://developer.gitter.im/apps) before getting started. A registered OAuth 2.0 application is assigned a unique Client ID and Client Secret. The Client Secret should not be shared. 8 | 9 | Given the security implications of getting the implementation correct, we strongly encourage you to use available OAuth 2.0 libraries. 10 | 11 | ## Demo App 12 | 13 | There's a Node.JS demo app you can clone and play with at [https://github.com/gitterHQ/gitter-demo-app](https://github.com/gitterHQ/gitter-demo-app) 14 | 15 | ### Web Application Flow 16 | 17 | [Authorization Code Grant](http://tools.ietf.org/html/rfc6749#section-4.1) is probably the most used authorization flow. The flow is based on redirects and requires the client to have a web browser. Use this flow if your client is another web application. 18 | 19 | #### 1. Redirect users to request Gitter access 20 | 21 | ``` 22 | GET https://gitter.im/login/oauth/authorize 23 | ``` 24 | 25 | 26 | The following query string parameters can be used: 27 | 28 | | Name | Description | 29 | | ------------- | ------------ | 30 | | client_id | **Required** The registered client ID for your application. | 31 | | response_type | **Required** Use value `code`. | 32 | | redirect_uri | The URL in your app where users will be sent after authorization. See details below about redirect URLs. | 33 | 34 | #### 2. Gitter redirects back to your site 35 | 36 | If the user accepts your request, Gitter redirects back to your site with a temporary authorization code in the redirect URL as well as the state parameter provided in the previous step. 37 | 38 | The redirect might look like 39 | 40 | ``` 41 | GET https://example.com/oauth/callback?code=deadbeef 42 | ``` 43 | 44 | Exchange the `code` for an access token with 45 | 46 | ``` 47 | POST https://gitter.im/login/oauth/token 48 | ``` 49 | 50 | The following parameters should be present in the request: 51 | 52 | | Field | Description | 53 | | -------------- | --------------------------------- | 54 | | client_id | **Required** The registered client ID for your application. | 55 | | client_secret | **Required** The client secret for your application. | 56 | | code | **Required** The authorization code returned from the initial request. | 57 | | redirect_uri | **Required** The URI registered with the application. | 58 | | grant_type | **Required** As defined in the OAuth 2.0 specification, this field must contain a value of `authorization_code`. | 59 | 60 | A successful response to this contains the following fields: 61 | 62 | | Field | Description | 63 | | -------------- | --------------------------------- | 64 | | access_token | The token that can be used to access the Gitter API. | 65 | | expires_in | The remaining lifetime on the access token. | 66 | | token_type | The type of token received. At this time, this field will always have the value `Bearer`. | 67 | 68 | By default, the response will be represented as an `application/x-www-form-urlencoded` string, such as 69 | 70 | access_token=[omitted]&scope=flow%2Cprivate&token_type=bearer 71 | 72 | However, you can also specify the JSON content type using the `Accept` header. 73 | 74 | Accept: application/json 75 | {"access_token":[omitted], "scope":"flow,private", "token_type":"bearer"} 76 | 77 | ### Testing OAuth2 exchange using curl: 78 | 79 | You can obtain a token using the command: 80 | 81 | ``` 82 | 'demo api-access'; 83 | { 84 | "verb": "post", 85 | "resource": "{{api_url}}/v1/rooms/:roomId/chatMessages/:chatMessageId", 86 | "data": { 87 | "client_id": "YOUR_CLIENT_ID", 88 | "client_secret": "YOUR_CLIENT_SECRET", 89 | "code": "CODE", 90 | "grant_type": "authorization_code", 91 | "redirect_uri": "YOUR_REDIRECT_URL" 92 | } 93 | } 94 | ``` 95 | 96 | #### 3. Make API requests with the access token. 97 | 98 | The access token allows you to make requests to the API on behalf of a user. 99 | 100 | GET https://api.gitter.im/v1/user 101 | Authorization: Bearer OAUTH-TOKEN 102 | Host: api.gitter.im 103 | 104 | 105 | ## Check who you are authenticated as 106 | 107 | ### Parameters 108 | 109 | - *none* 110 | 111 | ``` 112 | GET /v1/user/me 113 | ``` 114 | 115 | Try it from the CLI: 116 | ``` 117 | 'demo api-access'; 118 | { 119 | "verb": "get", 120 | "resource": "{{api_url}}/v1/user/me" 121 | } 122 | ``` 123 | 124 | ``` 125 | { 126 | "id": "553d437215522ed4b3df8c50", 127 | "username": "MadLittleMods", 128 | "displayName": "Eric Eastwood", 129 | "url": "/MadLittleMods", 130 | "avatarUrl": "https://avatars-05.gitter.im/gh/uv/3/MadLittleMods", 131 | "staff": true, 132 | "providers": [ 133 | "github" 134 | ], 135 | "v": 8, 136 | "gv": "3" 137 | } 138 | ``` 139 | -------------------------------------------------------------------------------- /06.User-resource.md: -------------------------------------------------------------------------------- 1 | # User 2 | 3 | Returns the current user logged in. 4 | 5 | ## User schema 6 | 7 | - `id`: Gitter User ID. 8 | - `username`: Gitter/GitHub username. 9 | - `displayName`: Gitter/GitHub user real name. 10 | - `url`: Path to the user on Gitter. 11 | - `avatarUrlSmall`: User avatar URI (small). 12 | - `avatarUrlMedium`: User avatar URI (medium). 13 | 14 | ## Get the current user 15 | 16 | ``` 17 | GET /v1/user 18 | ``` 19 | 20 | ``` 21 | [{ 22 | "id": "53307734c3599d1de448e192", 23 | "username": "malditogeek", 24 | "displayName": "Mauro Pompilio", 25 | "url": "/malditogeek", 26 | "avatarUrlSmall": "https://avatars.githubusercontent.com/u/14751?", 27 | "avatarUrlMedium": "https://avatars.githubusercontent.com/u/14751?" 28 | }] 29 | ``` 30 | 31 | Try it from the CLI: 32 | ``` 33 | 'demo api-access'; 34 | { 35 | "verb": "get", 36 | "resource": "{{api_url}}/v1/user" 37 | } 38 | ``` 39 | 40 | ## User sub-resources 41 | 42 | ### Rooms 43 | 44 | List of [Rooms](rooms-resource) the user is part of. 45 | 46 | ``` 47 | GET /v1/user/:userId/rooms 48 | ``` 49 | 50 | ``` 51 | [{ 52 | "id": "53307860c3599d1de448e19d", 53 | "name": "Andrew Newdigate", 54 | "topic": "", 55 | "oneToOne": true, 56 | "userCount": 2, 57 | "user": { 58 | "id": "53307831c3599d1de448e19a", 59 | "username": "suprememoocow", 60 | "displayName": "Andrew Newdigate", 61 | "url": "/suprememoocow", 62 | "avatarUrlSmall": "https://avatars.githubusercontent.com/u/594566?", 63 | "avatarUrlMedium": "https://avatars.githubusercontent.com/u/594566?" 64 | }, 65 | "unreadItems": 0, 66 | "mentions": 0, 67 | "lastAccessTime": "2014-04-24T15:53:25.662Z", 68 | "lurk": false, 69 | "url": "/suprememoocow", 70 | "githubType": "ONETOONE" 71 | }, { 72 | "id": "5330777dc3599d1de448e194", 73 | "name": "gitterHQ", 74 | "topic": "Gitter", 75 | "uri": "gitterHQ", 76 | "oneToOne": false, 77 | "userCount": 2, 78 | "unreadItems": 0, 79 | "mentions": 0, 80 | "lastAccessTime": "2014-04-24T17:34:00.738Z", 81 | "lurk": false, 82 | "url": "/gitterHQ", 83 | "githubType": "ORG", 84 | "v": 9 85 | }, { 86 | "id": "53307793c3599d1de448e196", 87 | "name": "malditogeek/vmux", 88 | "topic": "VMUX - Plugin-free video calls in your browser using WebRTC", 89 | "uri": "malditogeek/vmux", 90 | "oneToOne": false, 91 | "userCount": 2, 92 | "unreadItems": 0, 93 | "mentions": 0, 94 | "lastAccessTime": "2014-03-25T11:51:03.758Z", 95 | "lurk": false, 96 | "url": "/malditogeek/vmux", 97 | "githubType": "REPO", 98 | "v": 1 99 | }] 100 | ``` 101 | 102 | Try it from the CLI: 103 | ``` 104 | 'demo api-access'; 105 | { 106 | "verb": "get", 107 | "resource": "{{api_url}}/v1/user/:userId/rooms" 108 | } 109 | ``` 110 | 111 | ### Unread Items 112 | 113 | You can retrieve unread items and mentions using the following endpoint. 114 | 115 | ``` 116 | GET /v1/user/:userId/rooms/:roomId/unreadItems 117 | ``` 118 | 119 | ``` 120 | { 121 | "chat": [ 122 | "560ae5f495756f1402bc841d", 123 | "560aeef6f4b61c106fb2a9f3", 124 | "560aef2b552ed7913279df52" 125 | ], 126 | "mention": [ 127 | "560b167a967c1bad7852bc57" 128 | ] 129 | } 130 | ``` 131 | 132 | Try it from the CLI: 133 | ``` 134 | 'demo api-access'; 135 | { 136 | "verb": "get", 137 | "resource": "{{api_url}}/v1/user/:userId/rooms/:roomId/unreadItems" 138 | } 139 | ``` 140 | 141 | ### Mark Unread Items as "read" 142 | 143 | There is an additional endpoint nested under rooms that you can use to mark chat messages as read. 144 | 145 | #### Parameters 146 | 147 | - `chat`: Array of chatIds. 148 | 149 | ``` 150 | POST /v1/user/:userId/rooms/:roomId/unreadItems 151 | ``` 152 | 153 | ``` 154 | { 155 | "chat": [ 156 | "560ae5f495756f1402bc841d", 157 | "560aeef6f4b61c106fb2a9f3", 158 | "560aef2b552ed7913279df52", 159 | "560aef4f081f3a9c044d7d61" 160 | ] 161 | } 162 | ``` 163 | 164 | Try it from the CLI: 165 | ``` 166 | 'demo api-access'; 167 | { 168 | "verb": "post", 169 | "resource": "{{api_url}}/v1/user/:userId/rooms/:roomId/unreadItems", 170 | "data": { 171 | "chat": [ 172 | "560ae5f495756f1402bc841d", 173 | "560aeef6f4b61c106fb2a9f3", 174 | "560aef2b552ed7913279df52", 175 | "560aef4f081f3a9c044d7d61" 176 | ] 177 | } 178 | } 179 | ``` 180 | 181 | ### Orgs 182 | 183 | List of the user's GitHub Organisations and their respective [Room](rooms-resource) if available. 184 | 185 | ``` 186 | GET /v1/user/:userId/orgs 187 | ``` 188 | 189 | ``` 190 | [{ 191 | "id": 5990364, 192 | "name": "gitterHQ", 193 | "avatar_url": "https://avatars.githubusercontent.com/u/5990364?", 194 | "room": { 195 | "id": "5330777dc3599d1de448e194", 196 | "name": "gitterHQ", 197 | "topic": "Gitter", 198 | "uri": "gitterHQ", 199 | "oneToOne": false, 200 | "userCount": 2, 201 | "unreadItems": 0, 202 | "mentions": 0, 203 | "lastAccessTime": "2014-03-25T11:50:49.799Z", 204 | "lurk": false, 205 | "url": "/gitterHQ", 206 | "githubType": "ORG", 207 | "v": 1 208 | } 209 | }, { 210 | "id": 4046959, 211 | "name": "lnug", 212 | "avatar_url": "https://avatars.githubusercontent.com/u/4046959?" 213 | }] 214 | ``` 215 | 216 | Try it from the CLI: 217 | ``` 218 | 'demo api-access'; 219 | { 220 | "verb": "get", 221 | "resource": "{{api_url}}/v1/user/:userId/orgs" 222 | } 223 | ``` 224 | 225 | 226 | ### Repos 227 | 228 | List of the user's GitHub Repositories and their respective [Room](rooms-resource) if available. 229 | 230 | Note: It'll return private repositories if the current user has granted Gitter privileges to access them. 231 | 232 | ``` 233 | GET /v1/user/:userId/repos 234 | ``` 235 | 236 | ``` 237 | [{ 238 | "id": 10974239, 239 | "name": "malditogeek/vmux", 240 | "uri": "malditogeek/vmux", 241 | "private": false, 242 | "room": { 243 | "id": "53307793c3599d1de448e196", 244 | "name": "malditogeek/vmux", 245 | "topic": "VMUX - Plugin-free video calls in your browser using WebRTC", 246 | "uri": "malditogeek/vmux", 247 | "oneToOne": false, 248 | "userCount": 2, 249 | "unreadItems": 0, 250 | "mentions": 0, 251 | "lastAccessTime": "2014-03-25T11:51:03.758Z", 252 | "lurk": false, 253 | "url": "/malditogeek/vmux", 254 | "githubType": "REPO", 255 | "v": 1 256 | } 257 | }, { 258 | "id": 15316813, 259 | "name": "gitterHQ/marked", 260 | "uri": "gitterHQ/marked", 261 | "private": false 262 | }, { 263 | "id": 16485332, 264 | "name": "gitterHQ/emojify.js", 265 | "uri": "gitterHQ/emojify.js", 266 | "private": false 267 | }] 268 | ``` 269 | 270 | Try it from the CLI: 271 | ``` 272 | 'demo api-access'; 273 | { 274 | "verb": "get", 275 | "resource": "{{api_url}}/v1/user/:userId/repos" 276 | } 277 | ``` 278 | 279 | 280 | ### Channels 281 | 282 | List of [Gitter channels](rooms-resource#channels) nested under the current user. 283 | 284 | ``` 285 | GET /v1/user/:userId/channels 286 | ``` 287 | 288 | ``` 289 | [{ 290 | "id": "533177b9c3599d1de448e1a1", 291 | "name": "malditogeek/AMA", 292 | "topic": "", 293 | "uri": "malditogeek/AMA", 294 | "oneToOne": false, 295 | "unreadItems": 0, 296 | "mentions": 0, 297 | "lastAccessTime": "2014-03-25T12:34:03.681Z", 298 | "lurk": false, 299 | "url": "/malditogeek/AMA", 300 | "githubType": "USER_CHANNEL", 301 | "security": "PUBLIC" 302 | }] 303 | ``` 304 | 305 | Try it from the CLI: 306 | ``` 307 | 'demo api-access'; 308 | { 309 | "verb": "get", 310 | "resource": "{{api_url}}/v1/user/:userId/channels" 311 | } 312 | ``` 313 | -------------------------------------------------------------------------------- /04.Rooms-resource.md: -------------------------------------------------------------------------------- 1 | # Rooms 2 | 3 | A Room in Gitter can represent a GitHub Organisation, a GitHub Repository, a Gitter Channel or a One-to-one conversation. 4 | 5 | In the case of the Organisations and Repositories, the access control policies are inherited from GitHub. 6 | 7 | The following types of room exist: 8 | 9 | - `ORG`: A room that represents a GitHub Organisation. 10 | - `REPO`: A room that represents a GitHub Repository. 11 | - `ONETOONE`: A one-to-one chat. 12 | - `ORG_CHANNEL`: A Gitter channel nested under a GitHub Organisation. 13 | - `REPO_CHANNEL` A Gitter channel nested under a GitHub Repository. 14 | - `USER_CHANNEL` A Gitter channel nested under a GitHub User. 15 | 16 | ## Room schema 17 | 18 | - `id`: Room ID. 19 | - `name`: Room name. 20 | - `topic`: Room topic. (default: GitHub repo description) 21 | - `uri`: Room URI on Gitter. 22 | - `oneToOne`: Indicates if the room is a one-to-one chat. 23 | - `users`: List of users in the room. 24 | - `userCount`: Count of users in the room. 25 | - `unreadItems`: Number of unread messages for the current user. 26 | - `mentions`: Number of unread mentions for the current user. 27 | - `lastAccessTime`: Last time the current user accessed the room in ISO format. 28 | - `favourite`: Indicates if the room is on of your favourites. 29 | - `lurk`: Indicates if the current user has disabled notifications. 30 | - `url`: Path to the room on gitter. 31 | - `githubType`: Type of the room. 32 | - `tags`: Tags that define the room. 33 | - `v`: Room version. 34 | 35 | ## List rooms 36 | 37 | List rooms the current user is in. 38 | 39 | ### Parameters 40 | 41 | All the parameters are optional: 42 | 43 | - `q`: Search query 44 | 45 | ``` 46 | GET /v1/rooms 47 | ``` 48 | 49 | ``` 50 | [{ 51 | "id": "53307860c3599d1de448e19d", 52 | "name": "Andrew Newdigate", 53 | "topic": "", 54 | "oneToOne": true, 55 | "user": { 56 | "id": "53307831c3599d1de448e19a", 57 | "username": "suprememoocow", 58 | "displayName": "Andrew Newdigate", 59 | "url": "/suprememoocow", 60 | "avatarUrlSmall": "https://avatars.githubusercontent.com/u/594566?", 61 | "avatarUrlMedium": "https://avatars.githubusercontent.com/u/594566?" 62 | }, 63 | "unreadItems": 0, 64 | "mentions": 0, 65 | "lurk": false, 66 | "url": "/suprememoocow", 67 | "githubType": "ONETOONE" 68 | }, { 69 | "id": "5330777dc3599d1de448e194", 70 | "name": "gitterHQ", 71 | "topic": "Gitter", 72 | "uri": "gitterHQ", 73 | "oneToOne": false, 74 | "userCount": 2, 75 | "unreadItems": 0, 76 | "mentions": 0, 77 | "lastAccessTime": "2014-03-24T18:22:28.105Z", 78 | "lurk": false, 79 | "url": "/gitterHQ", 80 | "githubType": "ORG", 81 | "v": 1 82 | }, { 83 | "id": "5330780dc3599d1de448e198", 84 | "name": "gitterHQ/devops", 85 | "topic": "", 86 | "uri": "gitterHQ/devops", 87 | "oneToOne": false, 88 | "userCount": 2, 89 | "unreadItems": 0, 90 | "mentions": 0, 91 | "lastAccessTime": "2014-03-24T18:23:10.512Z", 92 | "lurk": false, 93 | "url": "/gitterHQ/devops", 94 | "githubType": "ORG_CHANNEL", 95 | "security": "INHERITED", 96 | "v": 1 97 | }, { 98 | "id": "53307793c3599d1de448e196", 99 | "name": "malditogeek/vmux", 100 | "topic": "VMUX - Plugin-free video calls in your browser using WebRTC", 101 | "uri": "malditogeek/vmux", 102 | "oneToOne": false, 103 | "userCount": 2, 104 | "unreadItems": 0, 105 | "mentions": 0, 106 | "lastAccessTime": "2014-03-24T18:21:08.448Z", 107 | "favourite": 1, 108 | "lurk": false, 109 | "url": "/malditogeek/vmux", 110 | "githubType": "REPO", 111 | "tags": [ 112 | "javascript", 113 | "nodejs" 114 | ], 115 | "v": 1 116 | }] 117 | ``` 118 | 119 | Try it from the CLI: 120 | ``` 121 | 'demo api-access'; 122 | { 123 | "verb": "get", 124 | "resource": "{{api_url}}/v1/rooms" 125 | } 126 | ``` 127 | 128 | 129 | ## Create a room 130 | 131 | **This is a private API.** You need to use the Gitter ecosystem to create a room. 132 | 133 | 134 | ## Join a room 135 | 136 | To join a room you'll need to provide a URI for it. Said URI can represent a GitHub Org, a GitHub Repo or a Gitter Channel: 137 | 138 | - If the room exists and the user has enough permission to access it, it'll be added to the room. 139 | 140 | ### Parameters 141 | 142 | #### Step #1: Grab the room ID from URI 143 | 144 | - `uri`: **Required** URI of the room you would like to join. 145 | 146 | Try it from the CLI: 147 | ``` 148 | 'demo api-access'; 149 | { 150 | "verb": "post", 151 | "resource": "{{api_url}}/v1/rooms", 152 | "data": { 153 | "uri": "gitterhq/sandbox" 154 | } 155 | } 156 | ``` 157 | 158 | which returns: 159 | 160 | ```json 161 | { 162 | "id": "52b42a52ed5ab0b3bf051b93", 163 | "name": "gitterHQ/sandbox", 164 | // ... 165 | } 166 | ``` 167 | 168 | #### Step #2: Join the room via ID 169 | 170 | - `id`: **Required** ID of the room you would like to join. 171 | 172 | Try it from the CLI: 173 | ``` 174 | 'demo api-access'; 175 | { 176 | "verb": "post", 177 | "resource": "{{api_url}}/v1/user/:userId/rooms", 178 | "data": { 179 | "id": "52b42a52ed5ab0b3bf051b93" 180 | } 181 | } 182 | ``` 183 | 184 | ## Remove user from room, also leave a room 185 | 186 | Remove a user from a room. 187 | 188 | This can be self-inflicted to leave the the room and remove room from your left menu. 189 | 190 | `/v1/rooms/:room_id/users/:user_id` 191 | 192 | ``` 193 | 'demo api-access'; 194 | { 195 | "verb": "delete", 196 | "resource": "{{api_url}}/v1/rooms/:room_id/users/:user_id" 197 | } 198 | ``` 199 | 200 | 201 | 202 | ## Update room 203 | 204 | ### Parameters 205 | 206 | - `topic`: Room topic. 207 | - `noindex`: Whether the room is indexed by search engines 208 | - `tags`: Tags that define the room. 209 | 210 | Try it from the CLI: 211 | ``` 212 | 'demo api-access'; 213 | { 214 | "verb": "put", 215 | "resource": "{{api_url}}/v1/rooms/:roomId", 216 | "data": { 217 | "topic": "Heya, come chat with us", 218 | "noindex": false, 219 | "tags": "foo, bar" 220 | } 221 | } 222 | ``` 223 | 224 | 225 | 226 | ## Delete a room 227 | 228 | Delete room 229 | 230 | ### Parameters 231 | 232 | Try it from the CLI: 233 | ``` 234 | 'demo api-access'; 235 | { 236 | "verb": "delete", 237 | "resource": "{{api_url}}/v1/rooms/:roomId" 238 | } 239 | ``` 240 | 241 | 242 | 243 | ## Room sub-resources 244 | 245 | ### Users 246 | 247 | List of [Users](user-resource) currently in the room. 248 | 249 | ### Parameters 250 | 251 | All the parameters are optional: 252 | 253 | - `q`: Search query 254 | - `skip`: Skip n users. 255 | - `limit`: maximum number of users to return (default 30). 256 | 257 | ``` 258 | GET /v1/rooms/:roomId/users 259 | ``` 260 | 261 | ``` 262 | [{ 263 | "id": "53307734c3599d1de448e192", 264 | "username": "malditogeek", 265 | "displayName": "Mauro Pompilio", 266 | "url": "/malditogeek", 267 | "avatarUrlSmall": "https://avatars.githubusercontent.com/u/14751?", 268 | "avatarUrlMedium": "https://avatars.githubusercontent.com/u/14751?", 269 | "role": "admin" 270 | }, { 271 | "id": "53307831c3599d1de448e19a", 272 | "username": "suprememoocow", 273 | "displayName": "Andrew Newdigate", 274 | "url": "/suprememoocow", 275 | "avatarUrlSmall": "https://avatars.githubusercontent.com/u/594566?", 276 | "avatarUrlMedium": "https://avatars.githubusercontent.com/u/594566?" 277 | }] 278 | ``` 279 | 280 | Try it from the CLI: 281 | ``` 282 | 'demo api-access'; 283 | { 284 | "verb": "get", 285 | "resource": "{{api_url}}/v1/rooms/53307793c3599d1de448e196/users" 286 | } 287 | ``` 288 | -------------------------------------------------------------------------------- /05.Messages-resource.md: -------------------------------------------------------------------------------- 1 | # Messages 2 | 3 | Messages represent individual chat messages sent to a room. They are a sub-resource of a room. 4 | 5 | ## Message schema 6 | 7 | - `id`: ID of the message. 8 | - `text`: Original message in plain-text/markdown. 9 | - `html`: HTML formatted message. 10 | - `sent`: ISO formatted date of the message. 11 | - `editedAt`: ISO formatted date of the message if edited. 12 | - `fromUser`: (User)[user-resource] that sent the message. 13 | - `unread`: Boolean that indicates if the current user has read the message. 14 | - `readBy`: Number of users that have read the message. 15 | - `urls`: List of URLs present in the message. 16 | - `mentions`: List of @Mentions in the message. 17 | - `issues`: List of #Issues referenced in the message. 18 | - `meta`: Metadata. This is currently not used for anything. 19 | - `v`: Version. 20 | - `gv`: Stands for "Gravatar version" and is used for cache busting. 21 | - `status`: Boolean that indicates whether the message is a status update (a `/me` command) 22 | 23 | ## List Messages 24 | 25 | List of messages in a room. 26 | 27 | ### Parameters 28 | 29 | All the parameters are optional: 30 | 31 | - `skip`: Skip n messages (constrained to 5000 or less). 32 | - `beforeId`: Get messages before `beforeId`. 33 | - `afterId`: Get messages after `afterId`. 34 | - `aroundId`: Get messages around `aroundId` including this message. 35 | - `limit`: Maximum number of messages to return (constrained to 100 or less). 36 | - `q`: Search query. 37 | 38 | ``` 39 | GET /v1/rooms/:roomId/chatMessages?limit=50 40 | ``` 41 | 42 | ``` 43 | GET /v1/rooms/:roomId/chatMessages?q=foo 44 | ``` 45 | 46 | ``` 47 | [{ 48 | "id": "53316dc47bfc1a000000000f", 49 | "text": "Hi @suprememoocow !", 50 | "html": "Hi @suprememoocow !", 51 | "sent": "2014-03-25T11:51:32.289Z", 52 | "editedAt": null, 53 | "fromUser": { 54 | "id": "53307734c3599d1de448e192", 55 | "username": "malditogeek", 56 | "displayName": "Mauro Pompilio", 57 | "url": "/malditogeek", 58 | "avatarUrlSmall": "https://avatars.githubusercontent.com/u/14751?", 59 | "avatarUrlMedium": "https://avatars.githubusercontent.com/u/14751?" 60 | }, 61 | "unread": false, 62 | "readBy": 0, 63 | "urls": [], 64 | "mentions": [{ 65 | "screenName": "suprememoocow", 66 | "userId": "53307831c3599d1de448e19a" 67 | }], 68 | "issues": [], 69 | "meta": {}, 70 | "v": 1 71 | }, { 72 | "id": "53316ec37bfc1a0000000011", 73 | "text": "I've been working on #11, it'll be ready to ship soon", 74 | "html": "I've been working on #11, it'll be ready to ship soon", 75 | "sent": "2014-03-25T11:55:47.537Z", 76 | "editedAt": null, 77 | "fromUser": { 78 | "id": "53307734c3599d1de448e192", 79 | "username": "malditogeek", 80 | "displayName": "Mauro Pompilio", 81 | "url": "/malditogeek", 82 | "avatarUrlSmall": "https://avatars.githubusercontent.com/u/14751?", 83 | "avatarUrlMedium": "https://avatars.githubusercontent.com/u/14751?" 84 | }, 85 | "unread": false, 86 | "readBy": 0, 87 | "urls": [], 88 | "mentions": [], 89 | "issues": [{ 90 | "number": "11" 91 | }], 92 | "meta": {}, 93 | "v": 1 94 | }] 95 | ``` 96 | 97 | Try it from the CLI: 98 | ``` 99 | 'demo api-access'; 100 | { 101 | "verb": "get", 102 | "resource": "{{api_url}}/v1/rooms/:roomId/chatMessages" 103 | } 104 | ``` 105 | 106 | ### Pagination 107 | 108 | The general pattern for fetching pages of chat messages is to load the first page: 109 | 110 | ``` 111 | GET /v1/rooms/:roomId/chatMessages?limit=50 112 | ``` 113 | 114 | When you're ready to load the next page of results, find the ID of the oldest 115 | message in the previous result set. In the previous example, this would be 116 | "53316dc47bfc1a000000000f". Pass this ID through in the `beforeId` parameter, like 117 | this: 118 | 119 | ``` 120 | GET /v1/rooms/:roomId/chatMessages?limit=50&beforeId=53316dc47bfc1a000000000f 121 | ``` 122 | 123 | Keep repeating this pattern until the number of results is less than the limit 124 | you've specified, or you get no results back at all. 125 | 126 | ## Get a single message 127 | 128 | There is also a way to retrieve a single message using its id. 129 | 130 | ``` 131 | GET https://api.gitter.im/v1/rooms/:roomId/chatMessages/:messageId 132 | ``` 133 | 134 | ``` 135 | { 136 | "id": "53316dc47bfc1a000000000f", 137 | "text": "Hi @suprememoocow !", 138 | "html": "Hi @suprememoocow !", 139 | "sent": "2014-03-25T11:51:32.289Z", 140 | "editedAt": null, 141 | "fromUser": { 142 | "id": "53307734c3599d1de448e192", 143 | "username": "malditogeek", 144 | "displayName": "Mauro Pompilio", 145 | "url": "/malditogeek", 146 | "avatarUrlSmall": "https://avatars.githubusercontent.com/u/14751?", 147 | "avatarUrlMedium": "https://avatars.githubusercontent.com/u/14751?" 148 | }, 149 | "unread": false, 150 | "readBy": 0, 151 | "urls": [], 152 | "mentions": [{ 153 | "screenName": "suprememoocow", 154 | "userId": "53307831c3599d1de448e19a" 155 | }], 156 | "issues": [], 157 | "meta": {}, 158 | "v": 1 159 | } 160 | ``` 161 | 162 | Try it from the CLI: 163 | ``` 164 | 'demo api-access'; 165 | { 166 | "verb": "get", 167 | "resource": "{{api_url}}/v1/rooms/:roomId/chatMessages/:messageId" 168 | } 169 | ``` 170 | 171 | ## Send a Message 172 | 173 | Send a message to a room. 174 | 175 | ### Parameters 176 | 177 | - `text`: **Required** Body of the message. 178 | - `status`: Boolean, set to true to indicate that the message is a status update (what `/me` uses) 179 | 180 | ``` 181 | POST /v1/rooms/:roomId/chatMessages 182 | ``` 183 | 184 | ``` 185 | { 186 | "id": "533171eb7bfc1a0000000012", 187 | "text": "You should also check https://irc.gitter.im/", 188 | "html": "You should also check https://irc.gitter.im/", 189 | "sent": "2014-03-25T12:09:15.292Z", 190 | "editedAt": null, 191 | "fromUser": { 192 | "id": "53307734c3599d1de448e192", 193 | "username": "malditogeek", 194 | "displayName": "Mauro Pompilio", 195 | "url": "/malditogeek", 196 | "avatarUrlSmall": "https://avatars.githubusercontent.com/u/14751?", 197 | "avatarUrlMedium": "https://avatars.githubusercontent.com/u/14751?" 198 | }, 199 | "unread": false, 200 | "readBy": 0, 201 | "urls": [{ 202 | "url": "https://irc.gitter.im/" 203 | }], 204 | "mentions": [], 205 | "issues": [], 206 | "meta": {}, 207 | "v": 1 208 | } 209 | ``` 210 | 211 | Try it from the CLI: 212 | ``` 213 | 'demo api-access'; 214 | { 215 | "verb": "post", 216 | "resource": "{{api_url}}/v1/rooms/:roomId/chatMessages", 217 | "data": { 218 | "text": "You should also check https://irc.gitter.im/" 219 | } 220 | } 221 | ``` 222 | 223 | 224 | ## Update a Message 225 | 226 | Update a message. 227 | 228 | ### Parameters 229 | 230 | - `text`: **Required** Body of the message. 231 | 232 | ``` 233 | PUT /v1/rooms/:roomId/chatMessages/:chatMessageId 234 | ``` 235 | 236 | ``` 237 | { 238 | "id": "533171eb7bfc1a0000000012", 239 | "text": "You should also check https://irc.gitter.im/ <3<3<3", 240 | "html": "You should also check https://irc.gitter.im/ <3<3<3", 241 | "sent": "2014-03-25T12:09:15.292Z", 242 | "editedAt": "2014-03-25T12:13:02.985Z", 243 | "fromUser": { 244 | "id": "53307734c3599d1de448e192", 245 | "username": "malditogeek", 246 | "displayName": "Mauro Pompilio", 247 | "url": "/malditogeek", 248 | "avatarUrlSmall": "https://avatars.githubusercontent.com/u/14751?", 249 | "avatarUrlMedium": "https://avatars.githubusercontent.com/u/14751?" 250 | }, 251 | "unread": false, 252 | "readBy": 0, 253 | "urls": [{ 254 | "url": "https://irc.gitter.im/" 255 | }], 256 | "mentions": [], 257 | "issues": [], 258 | "meta": {}, 259 | "v": 2 260 | } 261 | ``` 262 | 263 | Try it from the CLI: 264 | ``` 265 | 'demo api-access'; 266 | { 267 | "verb": "post", 268 | "resource": "{{api_url}}/v1/rooms/:roomId/chatMessages/:chatMessageId", 269 | "data": { 270 | "text": "You should also check https://irc.gitter.im/ <3<3<3" 271 | } 272 | } 273 | ``` 274 | 275 | ### Mark messages as read 276 | 277 | See [the *Unread Items* section on the Users resource page](user-resource#unread-items). 278 | --------------------------------------------------------------------------------