01.REST-API.md

REST API

Use the REST API to get information about rooms and post messages.

• Authentication
• Room resource
• Message resource
• User resource

HTTP Methods

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.

URL Breakdown

https://api.gitter.im/v1/rooms/:roomId/chatMessages

• https: The Gitter API is served over secure HTTP only.
• v1: API version.
• rooms: The resource which is being requested.
• roomId: The ID of the Room.
• 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.

Structure of an API request

Example of posting a message:

POST /v1/rooms/:roomId/chatMessages

Headers

Content-Type must be defined in the header of requests that contain data.

Content-Type: application/json
Accept: application/json
Authorization: Bearer {{token}}

Body

{
  "text":"Happy Hacking!"
}

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id":"5330521e20d939a3be000018",
  "text":"Happy Hacking!",
  "html":"Happy Hacking!",
  "sent":"2014-03-24T15:41:18.991Z",
  "editedAt":null,
  "fromUser":{
    "id":"5315ef029517002db7dde53b",
    "username":"malditogeek",
    "displayName":"Mauro Pompilio",
    "url":"/malditogeek",
    "avatarUrlSmall":"https://avatars.githubusercontent.com/u/14751?",
    "avatarUrlMedium":"https://avatars.githubusercontent.com/u/14751?",
    "v":2
  },
  "unread":false,
  "readBy":0,
  "urls":[],
  "mentions":[],
  "issues":[],
  "meta":{},
  "v":1
}