add outline of high-level API documentation

Author: trevorthornton

api/README.md

@@ -0,0 +1,44 @@
+# Working with the ArchivesSpace API
+
+## Authentication
+
+Most actions against the backend require you to be logged in as a user
+with the appropriate permissions. By sending a request like:
+
+     POST /users/admin/login?password=login
+
+your authentication request will be validated, and a session token
+will be returned in the JSON response for your request.  To remain
+authenticated, provide this token with subsequent requests in the
+`X-ArchivesSpace-Session` header.  For example:
+
+     X-ArchivesSpace-Session: 8e921ac9bbe9a4a947eee8a7c5fa8b4c81c51729935860c1adfed60a5e4202cb
+
+
+## CRUD
+
+The ArchivesSpace API provides CRUD-style interactions for a number of
+different "top-level" record types.  Working with records follows a
+fairly standard pattern:
+
+     # Get a paginated list of accessions from repository '123'
+     GET /repositories/123/accessions?page=1
+
+     # Create a new accession, returning the ID of the new record
+     POST /repositories/123/accessions
+     {... a JSON document satisfying JSONModel(:accession) here ...}
+
+     # Get a single accession (returned as a JSONModel(:accession) instance) using the ID returned by the previous request
+     GET /repositories/123/accessions/456
+
+     # Update an existing accession
+     POST /repositories/123/accessions/456
+     {... a JSON document satisfying JSONModel(:accession) here ...}
+
+
+## Detailed documentation
+
+* [GET requests (retrieving records)](./get_requests.md)
+* [POST requests (creating and updating records)](./post_requests./md)
+* [DELETE requests](./delete_requests)
+* [API reference](http://archivesspace.github.io/archivesspace/api/) - Includes a complete list of available endpoints and guidance for their use

api/delete_requests.md

@@ -0,0 +1,3 @@
+# Performing DELETE requests
+
+> Additional documentation needed

api/get_requests.md

@@ -0,0 +1,19 @@
+# Performing GET requests
+
+## Resolving associated records
+
+> Additional documentation needed
+
+## Requests for paginated results
+
+> Additional documentation needed
+
+## Working with long results sets
+
+> Additional documentation needed
+
+## Search requests
+
+> Additional documentation needed
+
+

api/post_requests.md

@@ -0,0 +1,9 @@
+# Performing POST requests
+
+## Updating existing records
+
+> Additional documentation needed
+
+## Creating new records
+
+> Additional documentation needed

architecture/api.md

@@ -1,9 +1,11 @@
 # Working with the ArchivesSpace API
 
+> See **API section** for more detailed documentation
+
 ## Authentication
 
 Most actions against the backend require you to be logged in as a user
-with the appropriate permissions.  By sending a request like:
+with the appropriate permissions. By sending a request like:
 
      POST /users/admin/login?password=login