REST API Notes

HTTP Status

When to use which status code.

Create Entry

This endpoint can be called by clients with Admin role to create a new entry.

URL: /api/clients

Method: POST

Auth required : YES

Body example:

{
  "client_id": "123456",
  "application_type": "public",
  "display_name": "Wisecards Android",
  "grant_types" : [ "password", "refresh_token" ]
}

Response:

Success Response

Condition: When the entry was accepted and created.

Code: 201 Created

Header:

Location: https://wisecards.tea.ch/api/clients/123456

Body:

{
  "client_id": "123456"
}

Error Responses

Condition: When the entry contains invalid values, see response body to get detailed messages.

Code: 400 Bad Request

Body:

{
  "errors": [
    {
      "status": "400",
      "detail": "client_id is not valid"
    },
    {
      "status": "400",
      "detail": "client_secret is not valid"
    }
  ]
}

Update Entry

This endpoint can be called by clients with Admin role.

URL: /api/clients/123456

Method: PATCH

Auth required : YES

Body example:

{
  "display_name": "Public Wisecards Client"
}

Response Summary

Success Response

Condition: When the entry was successfully updated.

Code: 204 No Content

Error Responses

Condition: When the entry contains invalid values, see response body to get detailed messages.

Code: 400 Bad Request

Body:

{
  "errors": [
    {
      "status": "400",
      "detail": "display_name is not valid"
    }
  ]
}

Delete Entry

When status code 202 is returned, the entry can be undeleted. To undelete it see Undelete Entry.

URL: /api/clients/123456

Method: DELETE

Auth required : YES

Response Summary

Undelete Entry

This is the same endpoint as the update. Updates with is_deleted other than false to an deleted will be rejected with status code 404.

URL: /api/clients/123456

Method: PATCH

Auth required : YES

Body example:

{
  "is_deleted": false
}

Response Summary