2 files changed, 102 insertions, 6 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)