http/json consistency updates

sections/accesses.md

@@ -1,9 +1,6 @@
 Accesses
 ========
 
-> <Clever quote about accesses>
-
-
 Get accesses
 ------------
 
@@ -44,12 +41,12 @@ Grant access
 
 You can get the ids of existing people on the account from the [people API](https://github.com/37signals/bcx-api/blob/master/sections/people.md).
 
-This will return `200 OK` if the access was granted successfully. If the user does not have access to grant further access to the project, `403 Forbidden` will be returned.
+This will return `204 No Content` if the access was granted successfully. If the user does not have access to grant further access to the project, `403 Forbidden` will be returned.
 
 
 Revoke access
 -------------
 
 * `DELETE /projects/1/accesses/1.json` will revoke the access of the person who's id is mentioned in the URL.  (Same goes for calendars with /calendars/ instead)
 
-This will return `200 OK` if the revoke was a success. If the user does not have access to revoke access from the project, `403 Forbidden` will be returned.
+This will return `204 No Content` if the revoke was a success. If the user does not have access to revoke access from the project, `403 Forbidden` will be returned.

sections/attachments.md

@@ -39,10 +39,11 @@ curl --data-binary @logo.png \
 
 
 Get attachments
------------
+---------------
 
 * `GET /projects/1/attachments.json` will show attachments for this
-* project with file metadata, urls, and associated attachables (Uploads, Messages, or Comments).
+project with file metadata, urls, and associated attachables (Uploads, Messages,
+or Comments) with a `200 OK` response.
 
 If you need more information about what the attachment is attached to, you can
 make another request to the `attachable`'s `url` parameter.

sections/calendar_events.md

@@ -125,7 +125,7 @@ Examples:
 }
 ```
 
-This will return `200 OK`, with the URL of the new calendar_event in the `Location` header, if the creation was a success. If the dates are not in the proper format, you'll get a `400 Bad Request`.
+This will return `201 Created`, with the URL of the new calendar_event in the `Location` header and a JSON representation of the event in the response body, if the creation was a success. If the dates are not in the proper format, you'll get a `400 Bad Request`.
 
 
 Update calendar event
@@ -144,10 +144,10 @@ Update calendar event
 }
 ```
 
-This will return `200 OK` if the creation was a success. If the dates are not in the proper format, you'll get a `400 Bad Request`.
+This will return `200 OK` if the creation was a success, with a JSON representation of the resource in the response body. If the dates are not in the proper format, you'll get a `400 Bad Request`.
 
 
 Delete calendar event
 ---------------------
 
-* `DELETE /projects/1/calendar_events/1.json` will delete the calendar event specified and return `200 OK` if that was successful. (The same for /calendars/)
+* `DELETE /projects/1/calendar_events/1.json` will delete the calendar event specified and return `204 No Content` if that was successful. (The same for /calendars/)

sections/calendars.md

@@ -67,7 +67,7 @@ Create calendar
 }
 ```
 
-This will return `200 OK`, with the location of the new calendar in the `Location` header, if the creation was a success.
+This will return `201 Created`, with the location of the new calendar in the `Location` header along with a representation of the calendar in JSON in the response body if the creation was a success (See the **Get calendar** endpoint).
 
 
 Update calendar
@@ -81,10 +81,10 @@ Update calendar
 }
 ```
 
-This will return `200 OK` if the update was a success. If the user does not have access to update the calendar, you'll see `403 Forbidden`.
+This will return `200 OK` if the update was a success, along with a represenation of the calendar in JSON (See the **Get calendar** endpoint). If the user does not have access to update the calendar, you'll see `403 Forbidden`.
 
 
 Delete calendar
--------------
+---------------
 
-* `DELETE /calendars/1.json` will delete the calendar specified and return `200 OK` if that was successful. If the user does not have access to delete the calendar, you'll see `403 Forbidden`.
+* `DELETE /calendars/1.json` will delete the calendar specified and return `204 No Content` if that was successful. If the user does not have access to delete the calendar, you'll see `403 Forbidden`.

sections/comments.md

@@ -38,8 +38,21 @@ Create comment
 }
 ```
 
-This will return `200 OK`, with the location of the commentable where the
-comment appears in the `Location` header, if the creation was a success.
+This will return `201 Created`, with a representation of the comment just created in the response body if the creation was a success. The topic can be accessed via the `topic_url` parameter. For example:
+
+```json
+{
+  "id": 1028592764,
+  "content": "Yeah, really, welcome!",
+  "created_at": "2012-03-22T16:56:48-05:00",
+  "updated_at": "2012-03-22T16:56:48-05:00",
+  "creator": {
+    "id": 149087659,
+    "name": "Jason Fried"
+  },
+  "topic_url": "https://basecamp.com/9999999/api/v1/messages/888888.json"
+}
+```
 
 ### Attaching files
 
@@ -70,4 +83,4 @@ attachments are allowed.
 Delete comment
 -------------
 
-* `DELETE /projects/1/comments/1.json` will delete the comment specified and return `200 OK` if that was successful. If the user does not have access to delete the comment, you'll see `403 Forbidden`.
+* `DELETE /projects/1/comments/1.json` will delete the comment specified and return `204 No Content` if that was successful. If the user does not have access to delete the comment, you'll see `403 Forbidden`.

sections/documents.md

@@ -1,8 +1,6 @@
 Documents
 ========
 
-> <Clever quote about documents>
-
 All documents are automatically version-tracked. The API only exposes the most recent version of a document, though. Also, in the web UI we provide lock tracking to make sure people don't overwrite each other's work. There's no such automatic protection via the API. You're responsible yourself for managing this. Of course, everything is versioned so there won't be any lost data.
 
 Get documents
@@ -71,7 +69,7 @@ Create document
 }
 ```
 
-This will return `200 OK`, with the location of the new project in the `Location` header, if the creation was a success.
+This will return `201 Created`, with the location of the new project in the `Location` header along with a JSON representation of the document in the response body, if the creation was a success. See the **Get document** endpoint for more info.
 
 
 Update document
@@ -86,10 +84,10 @@ Update document
 }
 ```
 
-This will return `200 OK` if the update was a success.
+This will return `200 OK` if the update was a success, along with a JSON representation of the document in the response body. See the **Get document** endpoint for more info.
 
 
 Delete document
 --------------
 
-* `DELETE /projects/1/documents/1.json` will delete the document specified and return `200 OK` if that was successful. If the user does not have access to delete the document, you'll see `403 Forbidden`.
+* `DELETE /projects/1/documents/1.json` will delete the document specified and return `204 No Content` if that was successful. If the user does not have access to delete the document, you'll see `403 Forbidden`.

sections/messages.md

@@ -54,8 +54,7 @@ Create message
 }
 ```
 
-This will return `200 OK`, with the location of the new project in the
-`Location` header, if the creation was a success.
+This will return `201 Created`, with the location of the new project in the `Location` header along with the current JSON representation of the message  if the creation was a success. See the **Get message* endpoint for more info.
 
 ### Attaching files
 
@@ -96,10 +95,10 @@ Update message
 }
 ```
 
-This will return `200 OK` if the update was a success. If the user does not have access to update the message, you'll see `403 Forbidden`.
+This will return `200 OK` if the update was a success, along with the current JSON representation of the message in the response body. If the user does not have access to update the message, you'll see `403 Forbidden`. See the **Get message** endpoint for more info.
 
 
 Delete message
 -------------
 
-* `DELETE /projects/1/messages/1.json` will delete the message specified and return `200 OK` if that was successful. If the user does not have access to delete the message, you'll see `403 Forbidden`.
+* `DELETE /projects/1/messages/1.json` will delete the message specified and return `204 No Content` if that was successful. If the user does not have access to delete the message, you'll see `403 Forbidden`.

sections/people.md

@@ -59,4 +59,4 @@ New people can be invited directly to projects via the [accesses API](https://gi
 Delete person
 ------------
 
-* `DELETE /people/1.json` will delete the person specified and return `200 OK` if that was successful. If the user does not have access to delete the person, you'll see `403 Forbidden`.
+* `DELETE /people/1.json` will delete the person specified and return `204 No Content` if that was successful. If the user does not have access to delete the person, you'll see `403 Forbidden`.

sections/projects.md

@@ -95,7 +95,7 @@ Create project
 }
 ```
 
-This will return `200 OK`, with the location of the new project in the `Location` header, if the creation was a success. If the user does not have access to create new projects or the account has reached the project limit, you'll see `403 Forbidden`.
+This will return `201 Created`, with the location of the new project in the `Location` header along with the current JSON representation of the project if the creation was a success. See the **Get project** endpoint for more info. If the user does not have access to create new projects or the account has reached the project limit, you'll see `403 Forbidden`.
 
 
 Update project
@@ -110,7 +110,7 @@ Update project
 }
 ```
 
-This will return `200 OK` if the update was a success. If the user does not have access to update the project, you'll see `403 Forbidden`.
+This will return `200 OK` if the update was a success along with the current JSON representation of the project. See the **Get project** endpoint for more info. If the user does not have access to update the project, you'll see `403 Forbidden`.
 
 
 Archiving/activating a project
@@ -124,10 +124,10 @@ Archiving/activating a project
 }
 ```
 
-This will return `200 OK` if the update was a success. If the user does not have access to update the project, you'll see `403 Forbidden`.
+This will return `200 OK` if the update was a success, along with the current JSON representation of the project. If the user does not have access to update the project, you'll see `403 Forbidden`.
 
 
 Delete project
 -------------
 
-* `DELETE /projects/1.json` will delete the project specified and return `200 OK` if that was successful. If the user does not have access to delete the project, you'll see `403 Forbidden`.
+* `DELETE /projects/1.json` will delete the project specified and return `204 No Content` if that was successful. If the user does not have access to delete the project, you'll see `403 Forbidden`.

sections/todolists.md

@@ -148,7 +148,7 @@ Create todolist
 }
 ```
 
-This will return `200 OK`, with the URL of the new todolist in the `Location` header, if the creation was a success.
+This will return `201 Created`, with the URL of the new todolist in the `Location` header along with the current JSON representation of the todolist if the creation was a success. See the **Get todolist** endpoint for more info.
 
 
 Update todolist
@@ -163,10 +163,10 @@ Update todolist
 }
 ```
 
-This will return `200 OK` if the creation was a success. If the user does not have access to update the todolist, you'll see `403 Forbidden`.
+This will return `200 OK` if the creation was a success along with the current JSON representation of the todolist in the response body. See the **Get todolist** endpoint for more info. If the user does not have access to update the todolist, you'll see `403 Forbidden`.
 
 
 Delete todolist
 --------------
 
-* `DELETE /projects/1/todolists/1.json` will delete the todolist specified and return `200 OK` if that was successful. If the user does not have access to delete the todolist, you'll see `403 Forbidden`.
+* `DELETE /projects/1/todolists/1.json` will delete the todolist specified and return `204 No Content` if that was successful. If the user does not have access to delete the todolist, you'll see `403 Forbidden`.

sections/todos.md

@@ -59,7 +59,7 @@ Create todo
 }
 ```
 
-This will return `200 OK`, with the URL of the new todo in the `Location` header, if the creation was a success. If the assignee type is unrecognized or the `due_at` is in a wrong format, you'll see a `400 Bad Request`.
+This will return `201 Created`, with the URL of the new todo in the `Location` header along with the current JSON representation of the todo if the creation was a success. See the **Get todo** endpoint for more info. If the assignee type is unrecognized or the `due_at` is in a wrong format, you'll see a `400 Bad Request`.
 
 
 Update todo
@@ -79,10 +79,10 @@ Update todo
 }
 ```
 
-This will return `200 OK` if the update was a success. If the assignee type is unrecognized or the `due_at` is in a wrong format, you'll see a `400 Bad Request`.
+This will return `200 OK` if the update was a success along with the current JSON representation of the todo in the response body. See the **Get todo** endpoint for more info. If the assignee type is unrecognized or the `due_at` is in a wrong format, you'll see a `400 Bad Request`.
 
 
 Delete todo
 ----------
 
-* `DELETE /projects/1/todos/1.json` will delete the todo specified and return `200 OK` if that was successful. If the user does not have access to delete the todo, you'll see `403 Forbidden`.
+* `DELETE /projects/1/todos/1.json` will delete the todo specified and return `204 No Content` if that was successful. If the user does not have access to delete the todo, you'll see `403 Forbidden`.

sections/uploads.md

@@ -9,6 +9,8 @@ Create uploads
 
 * `POST /projects/1/uploads.json` will create a new entry in the "Files" section on the given project, with the given attachment token.
 
+This endpoint will return a `201 Created` if successful, with the URL to the new uplaod in the `Location` header along with the current JSON representation of the upload. See the **Get upload** for more info.
+
 Attaching files requires both the token and the name of the attachment. The
 token is returned from the [Create attachments](https://github.com/37signals/bcx-api/blob/master/sections/attachments.md)
 endpoint, which you must hit first before creating an upload.