From 588f7e608a5108303b2815d6ee4c6c259ce00224 Mon Sep 17 00:00:00 2001
From: jricher <jricher@mitre.org>
Date: Fri, 26 Apr 2013 11:44:29 -0700
Subject: [PATCH] Updated Api (markdown)

---
 Api.md | 83 ++++++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 75 insertions(+), 8 deletions(-)

diff --git a/Api.md b/Api.md
index f27ab68..78faee4 100644
--- a/Api.md
+++ b/Api.md
@@ -4,7 +4,7 @@ The API may be accessed through an active web session within the application (ie
 
 ## Clients
 
-Manages all registered clients on the system, both statically and dynamically registered.
+Manages all registered clients on the system, both statically and dynamically registered. Note that in this API's data model, the **id** field is distinct from the **clientId** field used in OAuth. This is a deliberate distinction to allow the **clientId** to be edited through the API.
 
 Endpoint: **`/api/clients`**
 
@@ -16,7 +16,6 @@ Get a list of all clients on the system, returns results in `application/json`.
 
 ```
 [
-
     {
         "id": 1,
         "clientId": "client",
@@ -75,14 +74,12 @@ Get a list of all clients on the system, returns results in `application/json`.
         "idTokenValiditySeconds": 600,
         "createdAt": null
     }
-
 ]
 ```
 *Note:* This method will return different information depending on whether or not the authorized user is an administrator. A non-administrator will get a limited set of information back:
 
 ```
 [
-
     {
         "id": 1,
         "clientId": "client",
@@ -109,7 +106,6 @@ Create a new client on the system. Message body is an `application/json` object
 
 ```
 {
-        "id": 1,
         "clientId": "client",
         "clientSecret": "secret",
         "redirectUris": [
@@ -361,7 +357,6 @@ Get a list of all whitelists on the system, returns results in `application/json
 
 ```
 [
-
     {
         "id": 1,
         "creatorUserId": "jricher",
@@ -372,7 +367,6 @@ Get a list of all whitelists on the system, returns results in `application/json
             "profile"
         ]
     }
-
 ]
 ```
 
@@ -384,7 +378,6 @@ Create a new whitelist on the system. Message body is an `application/json` obje
 
 ```
 {
-        "id": 1,
         "creatorUserId": "jricher",
         "clientId": "client",
         "allowedScopes": [
@@ -447,8 +440,82 @@ Deletes the whitelist with the {id} in the URL.
 
 Returns HTTP 200 with an empty page on success.
 
+
 ## Blacklists
 
+Blacklist entries allow an administrator to determine which URLs may not be used as redirect URIs for any clients, either dynamically or statically registered.
+
+Endpoint: **`/api/blacklist`**
+
+### GET /api/blacklist
+
+_Requires **ROLE_USER** or **ROLE_ADMIN** access._
+
+Get a list of all blacklists on the system, returns results in `application/json`.
+
+```
+[
+    {
+        "id": 1,
+        "uri": "http://baddomain.com/"
+    },
+    {
+        "id": 2,
+        "uri": "http://evil.biz/"
+    }
+]
+```
+
+### POST /api/blacklist
+
+_Requires **ROLE_ADMIN** access._
+
+Create a new blacklist on the system. Message body is an `application/json` object with all information:
+
+```
+{
+        "uri": "http://baddomain.com/"
+}
+```
+
+The server will return an updated copy of the object in `application/json` format as described under **GET /api/blacklist/{id}** on success.
+
+### GET /api/blacklist/{id}
+
+_Requires **ROLE_USER** or **ROLE_ADMIN** access._
+
+Get information about a specific blacklist identified by {id} in the url, in `application/json` format. 
+
+For example, the call to `/api/blacklist/1` would return:
+
+```
+{
+        "uri": "http://baddomain.com/"
+}
+```
+
+### PUT /api/blacklist/{id}
+
+_Requires **ROLE_ADMIN** access._
+
+Update the information for the blacklist identified by {id} in the URL. The request body must be `application/json` describing the entire blacklist object:
+
+```
+{
+        "uri": "http://baddomain.com/"
+}
+```
+
+The server will return an updated copy of the object in `application/json` format as described under **GET /api/blacklist/{id}** on success.
+
+### DELETE /api/blacklist/{id}
+
+_Requires **ROLE_ADMIN** access._
+
+Deletes the blacklist with the {id} in the URL.
+
+Returns HTTP 200 with an empty page on success.
+
 ## System Scopes
 
 ## User Site Approvals
\ No newline at end of file