1 files changed, 96 insertions, 0 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
+```