practice-management-api-p

Practice management API

Introduction

Provides information and functionality to assist the managers of the consulting company to manage the practices within the firm

Overview

The following use case diagram shows how actors will interact with the API

You can edit this use case diagram here https://yuml.me/edit/bff6941d

Authentication

Authentication is managed by Open API Connect and Authorisiation is managed by OAUTH 2. We are using Auth0 to provide thes services

Response Codes


A number of codes are available for successful responses. However, the exact status in most cases can be inferred from the request, and multiple potential successful return codes encourage inconsistency and add an overhead for testing and debugging.

A successful response code should be one of the following:

HTTP Status Code

When Used

200

OK – used to indicate that the request was successfully processed, and has returned data to the consumer of the service.

201

Created – used when a request has resulted in the creation of a new resource, e.g. from a POST request.

202

Accepted – used when a request has been received for processing, but that processing hasn’t yet completed; for example, an asynchronous request.

204

No Content – used when a request has been successfully processed but has resulted in a response containing an empty body.


# Error Codes

Error status codes are:

HTTP Status Code

Description

400

Bad request – the incoming request does not conform to the expected schema definition. The data sent may not match the definition, or may be missing altogether.

401

Unauthorised – the requesting client has not authenticated successfully, or is attempting to access a resource that is protected.

403

Forbidden – the client is attempting to access a resource to which access has not been granted

404

Not Found – used when the requested resource cannot be located.

406

Not Acceptable – used when a request contains an Accept header that the service does not support. For experience APIs, prefer Status Code 400 .

409

Conflict – typically used when two requests are processed that request a PATCH on the same resource at the same time, resulting in potentially two copies of the same data. For experience APIs, prefer Status Code 400 .

410

Gone – this is used when a resource being requested has been intentionally removed, for example by a DELETE request. For experience APIs, prefer Status Code 400.

415

Unsupported Media Type – used when the client attempts to access a resource using a media type that is not supported by the server or resource. For experience APIs, prefer Status Code 400 .

429

Too Many Requests – this is used when a service implements rate limiting, and indicates that the client has exhausted the number of requests allocated to the client for a given time interval. For experience APIs, prefer Status Code 400 .




# Fault Codes

Fault status codes are:

HTTP Status Code

Description

500

Internal Server Error – an unexpected condition was encountered. Details about the error must NOT be returned to the client, as this has the potential to reveal technical details about the implementation to consumers of the service.

502

Bad Gateway - the server, while acting as a gateway or proxy, received an invalid response from the upstream server it accessed in attempting to fulfil the request.



Good

HTTP/1.1 400 Bad Request
{

"Errors": [

{

"Code": "ER-1-0002",

"Message": "Invalid request data",

"DeveloperMessage": “the SendDateTime must be provided in the request message",

"Links":[{
"Rel": "",
"Href": "http://codingstandards/errors/ER-1-0002",
"Description": "Invalid data",
"Type": "GET"

}
]
}

Rate limit

Is there a limit to the number of requests an user can send?

PUBLISHER

Marcus Davies

CATEGORIES

Imports

1