REST API Notes

HTTP Status

When to use which status code.

Code	Name	Condition
201	Created	When the entry was accepted and created.
202	Accepted	When the request was accepted but not processed.
204	No Content	When the entry was successfully updated.
400	Bad Request	When the entry contains invalid values, see response body to get detailed messages.
401	Unauthorized	When no valid token was provided.
403	Forbidden	When more entries are requested than allowed.
404	Not Found	When the entry was not found.
409	Conflict	When the entry contains values that are not allowed in domain logic.
422	Unprocessable Entity	When the entry contains invalid values, see response body to get detailed messages.
500	Internal Server Error	When an unexpected technical problem happened and the request cannot be processed.

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:

Code	Condition
201	When the entry was accepted and created.
400	When the request contains invalid values, see response body to get detailed messages.
401	When no valid token was provided.
409	When the entry contains values that are not allowed in domain logic.
422	When the entry contains invalid values, see response body to get detailed messages.
500	When an unexpected technical problem happened and the request cannot be processed.

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

Code	Condition
204	When the entry was successfully updated.
400	When the entry contains invalid values, see response body to get detailed messages.
401	When no valid token was provided.
404	When the entry contains values that are not allowed in domain logic.
500	When an unexpected technical problem happened and the request cannot be processed.

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

Code	Condition
200	When the entry was successfully deleted.
202	When the entry was queued to be deleted.
204	When the entry was successfully deleted. No content is returned.
401	When no valid token was provided.
404	When the entry contains values that are not allowed in domain logic.
500	When an unexpected technical problem happened and the request cannot be processed.

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

Code	Condition
204	When the entry was successfully undeleted.
400	When the entry contains invalid values, see response body to get detailed messages.
401	When no valid token was provided.
404	When the entry contains values that are not allowed in domain logic.
500	When an unexpected technical problem happened and the request cannot be processed.

Test

Create a test-file test.http

@apivar1 = somevalue
@apibody = somecontent
###
GET https://tea.ch/api/something/{{apivar1}}/{{$guid}}
Accept: application/json
###
POST https://tea.ch/api/something/{{apivar1}}/{{$guid}}
Accept: application/json
Content-Type: application/xml

{{somecontent}}