diff options
Diffstat (limited to 'doc/developer')
| -rw-r--r-- | doc/developer/API-Web-Service.md | 96 | ||||
| -rw-r--r-- | doc/developer/API.md | 12 | ||||
| -rw-r--r-- | doc/developer/Code-Contribution-Guidelines.md | 45 |
3 files changed, 103 insertions, 50 deletions
diff --git a/doc/developer/API-Web-Service.md b/doc/developer/API-Web-Service.md new file mode 100644 index 000000000..53ebc869c --- /dev/null +++ b/doc/developer/API-Web-Service.md @@ -0,0 +1,96 @@ +# Mattermost Web Service API + +This provides a basic overview of the Mattermost Web Service API. Drivers interfacing with this API are available in different languages. Current documentation focuses on the transport layer for the API and functional documentation will be developed next. + +All examples assume there is a Mattermost instance running at http://localhost:8065. + +## Schema + +All API access is done through `yourdomain.com/api/v1/`, with all data being sent and received as JSON. + + +## Authentication + +The majority of the Mattermost API involves interacting with teams. Therefore, most API methods require authentication as a user. There are two ways to authenticate into a Mattermost system. + +##### Session Token + +Make an HTTP POST to `yourdomain.com/api/v1/users/login` with a JSON body indicating the `name` of the team, the user's `email` and `password`. + +``` +curl -i -d '{"name":"exampleteam","email":"someone@nowhere.com","password":"thisisabadpassword"}' http://localhost:8065/api/v1/users/login +``` + +If successful, the response will contain a `Token` header and a User object in the body. + +``` +HTTP/1.1 200 OK +Set-Cookie: MMSID=hyr5dmb1mbb49c44qmx4whniso; Path=/; Max-Age=2592000; HttpOnly +Token: hyr5dmb1mbb49c44qmx4whniso +X-Ratelimit-Limit: 10 +X-Ratelimit-Remaining: 9 +X-Ratelimit-Reset: 1 +X-Request-Id: smda55ckcfy89b6tia58shk5fh +X-Version-Id: developer +Date: Fri, 11 Sep 2015 13:21:14 GMT +Content-Length: 657 +Content-Type: application/json; charset=utf-8 + +{{user object as json}} +``` + +Include the `Token` as part of the `Authentication` header on your future API requests with the `Bearer` method. + +``` +curl -i -H 'Authorization: Bearer hyr5dmb1mbb49c44qmx4whniso' http://localhost:8065/api/v1/users/me +``` + +That's it! You should now be able to access the API as the user you logged in as. + +##### OAuth2 + +Coming soon... + + +## Client Errors + +All errors will return an appropriate HTTP response code along with the following JSON body: + +``` +{ + "message": "", // the reason for the error + "detailed_error": "", // some extra details about the error + "request_id": "", // the ID of the request + "status_code": 0 // the HTTP status code +} +``` + + +## Rate Limiting + +Whenever you make an HTTP request to the Mattermost API you might notice the following headers included in the response: +``` +X-Ratelimit-Limit: 10 +X-Ratelimit-Remaining: 9 +X-Ratelimit-Reset: 1441983590 + +``` + +These headers are telling you your current rate limit status. + +Header | Description +:--------------------- |:----------- +X-Ratelimit-Limit | The maximum number of requests you can make per second. +X-Ratelimit-Remaining | The number of requests remaining in the current window. +X-Ratelimit-Reset | The remaining UTC epoch seconds before the rate limit resets. + +If you exceed your rate limit for a window you will receive the following error in the body of the response: +``` +HTTP/1.1 429 Too Many Requests +Date: Tue, 10 Sep 2015 11:20:28 GMT +X-RateLimit-Limit: 10 +X-RateLimit-Remaining: 0 +X-RateLimit-Reset: 1 + +limit exceeded +``` diff --git a/doc/developer/API.md b/doc/developer/API.md index 6327f1173..4c4b2f04e 100644 --- a/doc/developer/API.md +++ b/doc/developer/API.md @@ -2,7 +2,7 @@ Mattermost APIs let you integrate your favorite tools and services withing your Mattermost experience. -## Slack-compatible integration support +## Slack-compatible Webhooks To offer an alternative to propreitary SaaS services, Mattermost focuses on being "Slack-compatible, but not Slack limited". That means providing support for developers of Slack applications to easily extend their apps to Mattermost, as well as support and capabilities beyond what Slack offers. @@ -12,19 +12,19 @@ Incoming webhooks allow external applications to post messages into Mattermost c In addition to supporting Slack's incoming webhook formatting, Mattermost webhooks offer full support of industry-standard markdown formatting, including headings, tables and in-line images. -### Outgoing Webhooks (coming in Mattermost v1.2) +### [Outgoing Webhooks (in Mattermost v1.2)](https://github.com/mattermost/platform/blob/master/doc/integrations/webhooks/Outgoing-Webhooks.md) Outgoing webhooks allow external applications to receive webhook events from events happening within Mattermost channels and private groups via JSON payloads via HTTP POST requests sent to incoming webhook URLs defined by your applications. Over time, Mattermost outgoing webhooks will support not only Slack applications using a compatible format, but also offer optional events and triggers beyond Slack's feature set. -## Mattermost Drivers +## Mattermost Web Service API -Mattermost is written in Golang and React and designed as a self-hosted system, which differs from Slack's technical platform and focus on SaaS. Therefore the Mattermost drivers will differ from Slack's interfaces. +Mattermost offers a Web Service API accessible by Mattermost Drivers, listed below. Initial documentation on the [transport layer for the web service is available](API-Web-Service.md) and functional documentation is under development. -Another key difference is that as an open source project, you are welcome to access and use Mattermost's APIs on your installations the same way the core team would use them for buildling new features. +## Mattermost Drivers -While detailed documentation of the interfaces is pending, if you want to build deep integrations with Mattermost there are two drivers at the heart of the system: +Mattermost drivers offer access to the Mattermost web service API in different languages and frameworks. ### [ReactJS Javascript Driver](https://github.com/mattermost/platform/blob/master/web/react/utils/client.jsx) diff --git a/doc/developer/Code-Contribution-Guidelines.md b/doc/developer/Code-Contribution-Guidelines.md index 48bbf2491..18be4aa0b 100644 --- a/doc/developer/Code-Contribution-Guidelines.md +++ b/doc/developer/Code-Contribution-Guidelines.md @@ -1,48 +1,5 @@ # Code Contribution Guidelines -Thank you for your interest in contributing to Mattermost. This guide provides an overview of important information for contributors to know. - -## Choose a Ticket - -1. Review the list of [Good First Contribution](https://mattermost.atlassian.net/issues/?filter=10206) tickets listed in Jira. -2. These projects are intended to be a straight forward first pull requests from new contributors. -If you don't find something appropriate for your interests, please see the full list of tickets [Accepting Pull Requests](https://mattermost.atlassian.net/issues/?filter=10101). - -3. If you have any questions at all about a ticket, please post to the [Contributor Discussion section](http://forum.mattermost.org/) of the Mattermost forum, or email the [Mattermost Developer Mailing list](https://groups.google.com/a/mattermost.com/forum/#!forum/developer/join). - -## Install Mattermost and set up a Fork - -1. Follow [developer setup instructions](https://github.com/mattermost/platform/blob/master/doc/developer/Setup.md) to install Mattermost. - -2. Create a branch with <branch name> set to the ID of the ticket you're working on, for example ```PLT-394```, using command: - -``` -git checkout -b <branch name> -``` - -## Programming and Testing - -1. Please review the [Mattermost Style Guide](Style-Guide.md) prior to making changes. - - To keep code clean and well structured, Mattermost uses ESLint to check that pull requests adhere to style guidelines for React. Code will need to follow Mattermost's React style guidelines in order to pass the automated build tests when a pull request is submitted. - -2. Please make sure to thoroughly test your change before submitting a pull request. - - Please review the ["Fast, Obvious, Forgiving" experience design principles](http://www.mattermost.org/design-principles/) for Mattermost and check that your feature meets the criteria. Also, for any changes to user interface or help text, please read the changes out loud, as a quick and easy way to catch any inconsitencies. - - -## Submitting a Pull Request - -1. Please add yourself to the Mattermost [approved contributor list](https://docs.google.com/spreadsheets/d/1NTCeG-iL_VS9bFqtmHSfwETo5f-8MQ7oMDE5IUYJi_Y/pubhtml?gid=0&single=true) prior to submitting by completing the [contributor license agreement](http://www.mattermost.org/mattermost-contributor-agreement/). - -2. When you submit your pull request please make it against `master` and include the Ticket ID at the beginning of your pull request comment, followed by a colon. - - For example, for a ticket ID `PLT-394` start your comment with: `PLT-394:`. See [previously closed pull requests](https://github.com/mattermost/platform/pulls?q=is%3Apr+is%3Aclosed) for examples. - -3. Once submitted, your pull request will be checked via an automated build process and will be reviewed by at least two members of the Mattermost core team, who may either accept the PR or follow-up with feedback. It would then get merged into `master` for the next release. - -4. If you've included your mailing address in Step 1, you'll be receiving a [Limited Edition Mattermost Mug](http://forum.mattermost.org/t/limited-edition-mattermost-mugs/143) as a thank you gift after your first pull request has been accepted. - - +Please see [CONTRIBUTING.md](https://github.com/mattermost/platform/blob/master/CONTRIBUTING.md) |