ts-webapi 0.4.6

Library for my web API projects
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89

# API Style Guide


## Errors


- An error response **MUST NOT** contain a body unless otherwise specified in
  the table.
- The server **SHOULD** prefer to panic if an error would only be the result of
  an implementation error.

| Status | Guideline                                                                                           | Additional Details                                               |
| ------ | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| 400    | **MUST** be used for body validation problems and business problems.                                | **MUST** include a JSON body containing a `problems: Problem[]`. |
| 401    | **MUST** be used if the request contains no valid authorization.                                    | -                                                                |
| 403    | **MUST NOT** be used for fine grained authorization.                                                | -                                                                |
| 404    | **MUST** be used if a resource does not exist, and **MUST** be used for fine grained authorization. | -                                                                |
| 409    | **SHOULD NOT** be used, 400 **SHOULD** be used instead.                                             | -                                                                |
| 422    | **SHOULD** be used for malformed request content.                                                   | -                                                                |
| 500    | **MUST** be used for any server-side errors.                                                        | -                                                                |

### 400 Bad Request `Problem`


```json
{
  "type": "object",
  "required": ["pointer", "detail"],
  "properties": {
    "pointer": {
      "type": "string",
      "description": "a JSON pointer to the field in the request body that violates a condition",
      "format": "rfc6901"
    },
    "detail": {
      "type": "string",
      "description": "a short description of the condition the pointer violated",
      "examples": [
        "must be less than 64 characters",
        "contains invalid character `&`",
        "this product is out of stock"
      ]
    }
  }
}
```

## Authorization


### Actions


- Every of a resource **MUST** specify the actions that can be performed in it.
- An action **MAY** be specified on a part of a resource.
- An action **MUST NOT** be specified on the resource if that action is
  specified on a part of that resource.
- Actions **SHOULD** be one of:
  1. `view`
  1. `delete`
  1. `create`
  1. `edit`

### Classification


- Every action **MUST** have a classification.
- Classifications **MUST** be one of:
  1. `public`, action is available to any unauthenticated user.
  1. `authenticated`, action is available to any authenticated identities.
  1. `private`, action is available to select authenticated identities.
  1. `senstivie`, action is available to select authenticated identities, and
     requires explicit consent.
- Authorization **SHOULD** be applied against the classification for the action.
  This means, if `view identity.id` is `public`, then all authenticated
  identities **SHOULD** be able to view it.

### Sensitive actions


- A sensitive action **SHOULD** be any action that has large consequences if
  performed unintentionally.
- Sensitive actions **MUST** require a token where the `typ` is `consent` and
  the `act` is the specific action that is being performed. The `act` claim must
  be in the form: `METHOD /path/to/specific/resource`. For example:
  `DELETE /identities/abc`.

## Success responses


- GET requests **SHOULD** use the 200 OK status code.
- POST requests **SHOULD** use the 201 Created status code and **MUST** return
  the created resource in the response body.
- PUT requests **SHOULD** use the 200 OK status code and **MUST** return the
  modified resource in the response body.
- DELETE requests **SHOULD** use the 204 No Content status code and **MUST NOT**
  return the resource that was deleted.