Merge pull request diaspora#11 from cmrd-senya/errors

Add some error handling information

_includes/page_tree.html

@@ -1,4 +1,5 @@
 <ul class="{{ include.ulclasses | default: "nav nav-pills nav-stacked" }}">
   <li class="{% include active_class.html url="/" %}"><a href="{{ site.baseurl }}/index.html">Overview</a></li>
   <li class="{% include active_class.html url="/authentication.html" %}"><a href="{{ site.baseurl }}/authentication.html">Authentication</a></li>
+  <li class="{% include active_class.html url="/errors.html" %}"><a href="{{ site.baseurl }}/errors.html">Response codes and errors</a></li>
 </ul>

_routes/comments.md

@@ -41,6 +41,12 @@ GET /api/v1/posts/:post_guid/comments
 ]
 ~~~
 
+### Errors
+
+| Status code | Error reason                               |
+| ----------- | ------------------------------------------ |
+| 404         | Post with provided guid could not be found |
+
 ## Delete a comment
 
 Only the current users comments or comments written on the current users posts can be deleted.
@@ -57,6 +63,14 @@ DELETE /api/v1/posts/:post_guid/comments/:comment_guid
 Status: 204 No Content
 ~~~
 
+### Errors
+
+| Status code | Error reason                                  |
+| ----------- | --------------------------------------------- |
+| 403         | User not allowed to delete the comment        |
+| 404         | Post with provided guid could not be found    |
+| 404         | Comment with provided guid could not be found |
+
 ## Report a comment
 
 ### Request
@@ -76,6 +90,14 @@ POST /api/v1/posts/:post_guid/comments/:comment_guid/report
 Status: 204 No Content
 ~~~
 
+### Errors
+
+| Status code | Error reason                                     |
+| ----------- | ------------------------------------------------ |
+| 404         | Post with provided guid could not be found       |
+| 404         | Comment with provided guid could not be found    |
+| 409         | This item already has been reported by this user |
+
 ## Add a comment to a post
 
 ### Request
@@ -104,3 +126,11 @@ POST /api/v1/posts/:post_guid/comments
   "body": "Can I use these for my own website?"
 }
 ~~~
+
+### Errors
+
+| Status code | Error reason                               |
+| ----------- | ------------------------------------------ |
+| 404         | Post with provided guid could not be found |
+| 422         | User is not allowed to comment             |
+| 422         | Couldn't accept or process the comment     |

_routes/conversations.md

@@ -72,6 +72,10 @@ GET /api/v1/conversations
 ]
 ~~~
 
+### Errors
+
+No specific errors for this API endpoint.
+
 ## Get information about a single conversation
 
 ### Request
@@ -111,6 +115,12 @@ GET /api/v1/conversations/:conversation_guid
 }
 ~~~
 
+### Errors
+
+| Status code | Error reason                                       |
+| ----------- | -------------------------------------------------- |
+| 404         | Conversation with provided guid could not be found |
+
 ## Create new conversation
 
 ### Request
@@ -153,6 +163,12 @@ POST /api/v1/conversations
 }
 ~~~
 
+### Errors
+
+| Status code | Error reason                                |
+| ----------- | ------------------------------------------- |
+| 422         | Couldn't accept or process the conversation |
+
 ## Ignore and hide a conversation
 
 ### Request
@@ -167,6 +183,12 @@ DELETE /api/v1/conversations/:conversation_guid
 Status: 204 No Content
 ~~~
 
+### Errors
+
+| Status code | Error reason                                       |
+| ----------- | -------------------------------------------------- |
+| 404         | Conversation with provided guid could not be found |
+
 ## List messages in a conversation
 
 *Note*: This also marks the given conversation as read.
@@ -223,6 +245,12 @@ GET /api/v1/conversations/:conversation_guid/messages
 ]
 ~~~
 
+### Errors
+
+| Status code | Error reason                                       |
+| ----------- | -------------------------------------------------- |
+| 404         | Conversation with provided guid could not be found |
+
 ## Post new message to a conversation
 
 ### Request
@@ -251,3 +279,10 @@ POST /api/v1/conversations/:conversation_guid/messages
   }
 }
 ~~~
+
+### Errors
+
+| Status code | Error reason                                       |
+| ----------- | -------------------------------------------------- |
+| 404         | Conversation with provided guid could not be found |
+| 422         | Couldn't accept or process the conversation        |

_routes/likes.md

@@ -37,6 +37,12 @@ GET /api/v1/posts/:post_guid/likes
 ]
 ~~~
 
+### Errors
+
+| Status code | Error reason                               |
+| ----------- | ------------------------------------------ |
+| 404         | Post with provided guid could not be found |
+
 ## Like a post
 
 ### Request
@@ -51,6 +57,14 @@ POST /api/v1/posts/:post_guid/likes
 Status: 204 No Content
 ~~~
 
+### Errors
+
+| Status code | Error reason                               |
+| ----------- | ------------------------------------------ |
+| 404         | Post with provided guid could not be found |
+| 422         | User is not allowed to like                |
+| 422         | Like already exists                        |
+
 ## Unlike a post
 
 ### Request
@@ -64,3 +78,10 @@ DELETE /api/v1/posts/:post_guid/likes
 ~~~
 Status: 204 No Content
 ~~~
+
+### Errors
+
+| Status code | Error reason                               |
+| ----------- | ------------------------------------------ |
+| 404         | Post with provided guid could not be found |
+| 404         | Like doesn't exist                         |

_routes/posts.md

@@ -55,11 +55,11 @@ Mentioned people will be included in a separate array for advanced displaying. A
 
 One or more photos can be attached to a post. Images are provided in multiple resolutions, so bandwidth usage can be optimized.
 
-| Name   | Max. resolution   |
-| ------ | ----------------- |
-| large  | max. 700px width  |
-| medium | 100x100           |
-| small  | 50x50             |
+| Name   | Max. resolution  |
+| ------ | ---------------- |
+| large  | max. 700px width |
+| medium | 100x100          |
+| small  | 50x50            |
 
 ~~~json
 {
@@ -172,6 +172,12 @@ GET /api/v1/posts/:post_guid
 }
 ~~~
 
+### Errors
+
+| Status code | Error reason                               |
+| ----------- | ------------------------------------------ |
+| 404         | Post with provided guid could not be found |
+
 ## Publish a post
 
 ### Request
@@ -227,6 +233,13 @@ POST /api/v1/posts
 }
 ~~~
 
+### Errors
+
+| Status code | Error reason              | TODO notes                                                                                                                            |
+| ----------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| 403         | Failed to create the post | This is the status code of the present (non-API) status message controller. Feels sensible to change that to 422 or 400 or something. |
+
+
 ## Delete a post
 
 ### Request
@@ -240,3 +253,8 @@ DELETE /api/v1/posts/:post_guid
 ~~~
 Status: 204 No Content
 ~~~
+
+| Status code | Error reason                               |
+| ----------- | ------------------------------------------ |
+| 404         | Post with provided guid could not be found |
+| 403         | Not allowed to delete the post             |

_routes/streams.md

@@ -62,6 +62,10 @@ GET /api/v1/streams/main
 ]
 ~~~
 
+### Errors
+
+No specific errors for this API endpoint.
+
 ## Get aspect stream
 
 Contains all posts in some or all aspects. If `aspect_ids` is empty, all aspects are considered.
@@ -82,6 +86,10 @@ GET /api/v1/streams/aspects
 
 See [Main Stream Response example](#response).
 
+### Errors
+
+No specific errors for this API endpoint.
+
 ## Get activity stream
 
 Contains all posts on which the currently authenticated user interacted on, ordered by their last activity.
@@ -96,6 +104,10 @@ GET /api/v1/streams/activity
 
 See [Main Stream Response example](#response).
 
+### Errors
+
+No specific errors for this API endpoint.
+
 ##  Get mentions stream
 
 Contains all posts in which the currently authenticated user is mentioned, ordered by their creation timestamp.
@@ -110,6 +122,10 @@ GET /api/v1/streams/mentions
 
 See [Main Stream Response example](#response).
 
+### Errors
+
+No specific errors for this API endpoint.
+
 ## Get tag stream
 
 Contains posts tagged with one or more tags followed by the currently authenticated user.
@@ -124,6 +140,10 @@ GET /api/v1/streams/tags
 
 See [Main Stream Response example](#response).
 
+### Errors
+
+No specific errors for this API endpoint.
+
 ## Get liked stream
 
 Contains posts liked by the currently authenticated user.
@@ -138,6 +158,10 @@ GET /api/v1/streams/liked
 
 See [Main Stream Response example](#response).
 
+### Errors
+
+No specific errors for this API endpoint.
+
 ## Get commented stream
 
 Contains posts commented by the currently authenticated user.
@@ -151,3 +175,7 @@ GET /api/v1/streams/commented
 ### Response
 
 See [Main Stream Response example](#response).
+
+### Errors
+
+No specific errors for this API endpoint.

_routes/users.md

@@ -38,6 +38,10 @@ GET /api/v1/user
 }
 ~~~
 
+### Errors
+
+No specific errors for this API endpoint.
+
 ## Update the currently authenticated users profile
 
 ### Request
@@ -92,6 +96,12 @@ PATCH /api/v1/user
 }
 ~~~
 
+### Errors
+
+| Status code | Error reason               |
+| ----------- | -------------------------- |
+| 400         | Wrong value of a parameter |
+
 ## Get information about a single user
 
 Please note that the amount of information you retrieve from this request depends on whether the requested person shares with the currently authenticated user or not.
@@ -136,6 +146,12 @@ GET /api/v1/users/:person_guid
 }
 ~~~
 
+### Errors
+
+| Status code | Error reason                               |
+| ----------- | ------------------------------------------ |
+| 404         | User with provided guid could not be found |
+
 ## Get contacts from a single user
 
 Please note that, depending on the users aspect settings, you might not see other contacts and get an empty response instead.
@@ -165,6 +181,12 @@ GET /api/v1/users/:person_guid/contacts
 ]
 ~~~
 
+### Errors
+
+| Status code | Error reason                               |
+| ----------- | ------------------------------------------ |
+| 404         | User with provided guid could not be found |
+
 ## Get posts by a single user
 
 ### Request
@@ -221,6 +243,12 @@ GET /api/v1/users/:person_guid/posts
 ]
 ~~~
 
+### Errors
+
+| Status code | Error reason                               |
+| ----------- | ------------------------------------------ |
+| 404         | User with provided guid could not be found |
+
 ## Get photos by a single user
 
 ### Request
@@ -259,3 +287,9 @@ GET /api/v1/users/:person_guid/photos
   }
 ]
 ~~~
+
+### Errors
+
+| Status code | Error reason                               |
+| ----------- | ------------------------------------------ |
+| 404         | User with provided guid could not be found |

authentication.md

@@ -138,6 +138,12 @@ There are multiple ways of transmitting access tokens:
 * as an `application/x-www-form-urlencoded` parameter: `access_token=[access token]`
 * inside the request header: `Authorization: Bearer [access token]`
 
+## Authentication errors
+
+All API nodes require authentication. If no token or an invlaid token is supplied, the API will always return `401 Unauthorized`.
+
+If the client tries to access an OAuth scope that was not part of the authorization, the API will return `403 Forbidden`.
+
 ## Additional information and specifications
 
 * [OpenID Connect Core 1.0][connect] specification including flow descriptions