From 99402e9d99a1d9ac6b8b0d177e9098fe7657af0e Mon Sep 17 00:00:00 2001 From: it33 Date: Thu, 29 Oct 2015 07:00:20 -0700 Subject: Update and rename doc/api/Overview.md to doc/developer/API-Web-Service.md Per discussion with CH, moving this over to /developer and working to integrate it into: https://github.com/mattermost/platform/blob/master/doc/developer/API.md This is a multi-step process, we need to get everything under /developer, then explain from https://github.com/mattermost/platform/blob/master/doc/developer/API.md where to find everything. Documentation won't be perfect in first go, but we need to react quickly to community having questions around this. --- doc/api/Overview.md | 94 ----------------------------------------------------- 1 file changed, 94 deletions(-) delete mode 100644 doc/api/Overview.md (limited to 'doc/api/Overview.md') diff --git a/doc/api/Overview.md b/doc/api/Overview.md deleted file mode 100644 index 0a407b1e9..000000000 --- a/doc/api/Overview.md +++ /dev/null @@ -1,94 +0,0 @@ -# API Overview - -This provides a basic overview of the Mattermost API. 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 -``` -- cgit v1.2.3-1-g7c22