diff --git a/apiary.apib b/apiary.apib index 60a2cfd..46f5ab8 100644 --- a/apiary.apib +++ b/apiary.apib @@ -557,7 +557,7 @@ All custom user data is stored in the profile. Every account has an associated profile, by default, an empty one is created when creating the account. -### Fetch user profile [GET] +### Fetch [GET] + Request @@ -601,7 +601,7 @@ is created when creating the account. }] } -### Update user profile [PATCH] +### Update [PATCH] + Request (application/vnd.api+json) @@ -655,10 +655,193 @@ is created when creating the account. } +## Group Requests + + +## Request Collection [/requests] + +A user can only see own requests. An admin can see all requests across accounts. + +### List all [GET] + ++ Request + + + Headers + + Accept: application/vnd.api+json + Authorization: Bearer sessionid123 + ++ Response 200 (application/vnd.api+json) + + { + "links": { + "self": "https://example.com/requests", + "first": "https://example.com/requests", + "last": "https://example.com/requests?page=2", + "next": "https://example.com/requests?page=2" + }, + "data": [ + { + "id": "1234", + "type": "request", + "links": { + "self": "https://example.com/requests/1234" + }, + "attributes": { + "type": "passwordreset", + "contact": "john@example.com", + "expires": "2015-07-20T10:00:00-04:00" + } + }, + { + "id": "2345", + "type": "request", + "links": { + "self": "https://example.com/requests/2345" + }, + "attributes": { + "type": "usernamereminder", + "contact": "jane@example.com", + "expires": "2015-07-20T15:00:00-04:00" + } + } + ] + } + ++ Response 401 (application/vnd.api+json) + + { + errors: [{ + "status": "401", + "title": "Unauthorized", + "detail": "Invalid Credentials" + }] + } + +### Create [POST] + ++ Request (application/vnd.api+json) + + + Headers + + Accept: application/vnd.api+json + + + Body + + { + "data": { + "type": "request", + "attributes": { + "type": "passwordreset", + "contact": "john@example.com" + } + } + } + ++ Response 201 (application/vnd.api+json) + + + Headers + + Location: https://example.com/requests/1234 + + + Body + + { + "links": { + "self": "https://example.com/requests/1234" + }, + "data": { + "id": "1234", + "type": "request", + "attributes": { + "type": "passwordreset", + "contact": "john@example.com", + "expires": "2015-07-20T15:00:00-04:00" + } + } + } + ++ Response 401 (application/vnd.api+json) + + { + errors: [{ + "status": "401", + "title": "Unauthorized", + "detail": "Invalid Credentials" + }] + } + ++ Response 409 (application/vnd.api+json) + + { + errors: [{ + "status": "409", + "title": "Conflict", + "detail": "Invalid type provided, only supported type is 'request'" + }] + } + + +## Request [/requests/{id}] + +`DELETE` is restricted to admins. `GET` makes sense for users to check +for errors that might have occured after creating a request, +like an error during password reset delivery. + ++ Parameters + + id: 1234 (required, string) - request id + +### Fetch [GET] + ++ Request + + + Headers + + Accept: application/vnd.api+json + ++ Response 200 (application/vnd.api+json) + + { + "links": { + "self": "https://example.com/requests/1234" + }, + "data": { + "id": "1234", + "type": "request", + "attributes": { + "type": "passwordreset", + "contact": "john@example.com", + "expires": "2015-07-20T15:00:00-04:00" + } + } + } + +### Delete [DELETE] + ++ Request + + + Headers + + Accept: application/vnd.api+json + Authorization: Bearer sessionid123 + ++ Response 204 + ++ Response 401 (application/vnd.api+json) + + { + errors: [{ + "status": "401", + "title": "Unauthorized", + "detail": "Invalid Credentials" + }] + } + + ## Group Admins -## Accounts [/accounts] +## User Account Collection [/accounts] Admins can fetch and manage all user accounts and their profile properties @@ -810,7 +993,7 @@ Admins can fetch and manage all user accounts and their profile properties } -## Account [/accounts/{id}] +## User Account [/accounts/{id}] + Parameters @@ -979,7 +1162,7 @@ Admins can fetch and manage all user accounts and their profile properties } -## Profile [/accounts/{id}/profile] +## User Profile [/accounts/{id}/profile] All custom user data is stored in the profile. @@ -987,7 +1170,7 @@ All custom user data is stored in the profile. + id: abc4567 (required, string) - id of account -### Fetch user profile [GET] +### Fetch [GET] + Request @@ -1021,7 +1204,7 @@ All custom user data is stored in the profile. }] } -### Update user profile [PATCH] +### Update [PATCH] + Request (application/vnd.api+json) @@ -1063,183 +1246,3 @@ All custom user data is stored in the profile. "detail": "'type' and 'id' provided don't match any existing document" }] } - - -## requests [/requests] - -`GET` is restricted to admins. - -### List [GET] - -+ Request - - + Headers - - Accept: application/vnd.api+json - Authorization: Bearer sessionid123 - -+ Response 200 (application/vnd.api+json) - - { - "links": { - "self": "https://example.com/requests", - "first": "https://example.com/requests", - "last": "https://example.com/requests?page=2", - "next": "https://example.com/requests?page=2" - }, - "data": [ - { - "id": "1234", - "type": "request", - "links": { - "self": "https://example.com/requests/1234" - }, - "attributes": { - "type": "passwordreset", - "contact": "john@example.com", - "expires": "2015-07-20T10:00:00-04:00" - } - }, - { - "id": "2345", - "type": "request", - "links": { - "self": "https://example.com/requests/2345" - }, - "attributes": { - "type": "usernamereminder", - "contact": "jane@example.com", - "expires": "2015-07-20T15:00:00-04:00" - } - } - ] - } - -+ Response 401 (application/vnd.api+json) - - { - errors: [{ - "status": "401", - "title": "Unauthorized", - "detail": "Invalid Credentials" - }] - } - -### CREATE [POST] - -+ Request (application/vnd.api+json) - - + Headers - - Accept: application/vnd.api+json - - + Body - - { - "data": { - "type": "request", - "attributes": { - "type": "passwordreset", - "contact": "john@example.com" - } - } - } - -+ Response 201 (application/vnd.api+json) - - + Headers - - Location: https://example.com/requests/1234 - - + Body - - { - "links": { - "self": "https://example.com/requests/1234" - }, - "data": { - "id": "1234", - "type": "request", - "attributes": { - "type": "passwordreset", - "contact": "john@example.com", - "expires": "2015-07-20T15:00:00-04:00" - } - } - } - -+ Response 401 (application/vnd.api+json) - - { - errors: [{ - "status": "401", - "title": "Unauthorized", - "detail": "Invalid Credentials" - }] - } - -+ Response 409 (application/vnd.api+json) - - { - errors: [{ - "status": "409", - "title": "Conflict", - "detail": "Invalid type provided, only supported type is 'request'" - }] - } - - -## Request [/requests/{id}] - -`DELETE` is restricted to admins. `GET` makes sense for users to check -for errors that might have occured after creating a request, -like an error during password reset delivery. - -+ Parameters - + id: 1234 (required, string) - request id - -### Fetch request by id [GET] - -+ Request - - + Headers - - Accept: application/vnd.api+json - -+ Response 200 (application/vnd.api+json) - - { - "links": { - "self": "https://example.com/requests/1234" - }, - "data": { - "id": "1234", - "type": "request", - "attributes": { - "type": "passwordreset", - "contact": "john@example.com", - "expires": "2015-07-20T15:00:00-04:00" - } - } - } - -### Delete request [DELETE] - -+ Request - - + Headers - - Accept: application/vnd.api+json - Authorization: Bearer sessionid123 - -+ Response 204 - -+ Response 401 (application/vnd.api+json) - - { - errors: [{ - "status": "401", - "title": "Unauthorized", - "detail": "Invalid Credentials" - }] - }