Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

PII description and removal from examples #84

Closed
wants to merge 1 commit into from
Closed

PII description and removal from examples #84

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 26 additions & 22 deletions sections/hypermedia.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,13 @@ ______________________________________________________________________________

Hypermedia links in APIs are links in the response payload that inform the consumers to what contents can be retrieved. Though simple in concept hypermedia links in APIs allow consumers to locate resource without the need to have an upfront understanding of the resource and its relationship.

This is similar to the navigation of a web page. The user is not expected to know the structure of the web page prior to visiting. They can simply browse to the home page and the navigation lets them browse the site as required.
This is similar to the navigation of a web page. The user is not expected to know the structure of the web page prior to visiting. They can simply browse to the home page and the navigation lets them browse the site as required.

APIs that do not provide links are difficult to use and expect the consumer to refer to the documentation.
APIs that do not provide links expect the consumer to refer to the documentation.

The exclusion of Personally Identifiable Information (PII) in links provided back to a consumer should be a security / privacy consideration when referencing entities related to citizens, businesses, or any other entity considered to be non-discoverable, protected or sensitive in nature. The underlying reason for not including PII in links in particular is related to browsers and network devices being able to record and reference GET request information indefinitely.

References to such entities should be non-enumerable i.e. knowing one reference shouldn't allow the simple discovery of another (e.g. entities referenced with id=123 allow the enumeration of references id=122, id=124 etc). The use of UUIDs can be considered a good replacement for sequential references e.g. `6df54d5e-3df7-11ec-96ad-6f2d87ff1821` is non-enumerable. A reference may be also constructed using [pseudonymization techniques](https://en.wikipedia.org/wiki/Pseudonymization), in the case of OIDC "Subjects" the [Pairwise Identifier Algorithm](https://openid.net/specs/openid-connect-core-1_0.html#PairwiseAlg) may be used i.e. the identifier is non-enumerable and persistent only for the authenticated caller, however will not be resolvable for a different caller under a different authentication context. In some circumstances producing transient, short-lived, non-persistent or one-time-use references for entities may be appropriate (if explicitly understood and handled by the service & caller. Confirmation / reset links may be an appropriate example of this).

Example:

Expand All @@ -26,7 +30,7 @@ GET /namespace/v1/employees
"employees": [{
"name" : "John Smith",
"_links": [{
"href" : "/namespace/v1/employees/john-smith",
"href" : "/namespace/v1/employees/6df54d5e-3df7-11ec-96ad-6f2d87ff1821",
"rel" : "self"
}]
}]
Expand All @@ -39,12 +43,12 @@ GET /namespace/v1/employees

```javascript
{
"account_number":"12345",
"account_ref":"a2be47d4-3dfc-11ec-a765-db48afd2ce06",
"balance": 100.00,
"_links":[
{"rel": " **deposit**", "href":"/accounts/12345/deposit"},
{"rel": " **withdraw**", "href":"/accounts/12345/withdraw"},
{"rel": " **transfer**", "href":"/accounts/12345/transfer"}
{"rel": " **deposit**", "href":"/accounts/a2be47d4-3dfc-11ec-a765-db48afd2ce06/deposit"},
{"rel": " **withdraw**", "href":"/accounts/a2be47d4-3dfc-11ec-a765-db48afd2ce06/withdraw"},
{"rel": " **transfer**", "href":"/accounts/a2be47d4-3dfc-11ec-a765-db48afd2ce06/transfer"}
]
}

Expand All @@ -54,11 +58,11 @@ But if the same account is overdrawn by 25 then the only allowed action is depos

```javascript
{
"account_number":"12345",
"account_ref":"a2be47d4-3dfc-11ec-a765-db48afd2ce06",
"balance": -25.00,
"_links":[{
"rel": "deposit",
"href":"/accounts/12345/deposit"
"href":"/accounts/a2be47d4-3dfc-11ec-a765-db48afd2ce06/deposit"
}]
}

Expand Down Expand Up @@ -103,28 +107,28 @@ The API creates a new user from the input and returns the following links to the
```json
HTTP/1.1 201 CREATED
Content-Type: application/json
Location: https://gw.api.gov.au/dept-xyz/v1/users/ALT-JFWXHGUV7VI
Location: https://gw.api.gov.au/dept-xyz/v1/users/e7c9ad70-3dff-11ec-9d87-6fc27f396179
...

{
"_links": [
{
"href": "https://gw.api.gov.au/dept-xyz/v1/users/ALT-JFWXHGUV7VI",
"href": "https://gw.api.gov.au/dept-xyz/v1/users/e7c9ad70-3dff-11ec-9d87-6fc27f396179",
"rel": "self",
"method" : "GET"
},
{
"href": "https://gw.api.gov.au/dept-xyz/v1/users/ALT-JFWXHGUV7VI",
"href": "https://gw.api.gov.au/dept-xyz/v1/users/e7c9ad70-3dff-11ec-9d87-6fc27f396179",
"rel": "delete",
"method": "DELETE"
},
{
"href": "https://gw.api.gov.au/dept-xyz/v1/users/ALT-JFWXHGUV7VI",
"href": "https://gw.api.gov.au/dept-xyz/v1/users/e7c9ad70-3dff-11ec-9d87-6fc27f396179",
"rel": "replace",
"method": "PUT"
},
{
"href": "https://gw.api.gov.au/dept-xyz/v1/users/ALT-JFWXHGUV7VI",
"href": "https://gw.api.gov.au/dept-xyz/v1/users/e7c9ad70-3dff-11ec-9d87-6fc27f396179",
"rel": "edit",
"method": "PATCH"
}
Expand Down Expand Up @@ -162,7 +166,7 @@ Content-Type: application/json
...
"_links": [
{
"href": "https://gw.api.gov.au/dept-xyz/v1/users/ALT-JFWXHGUV7VI",
"href": "https://gw.api.gov.au/dept-xyz/v1/users/e7c9ad70-3dff-11ec-9d87-6fc27f396179",
"rel": "self"
}
]
Expand All @@ -173,7 +177,7 @@ Content-Type: application/json
...
"_links": [
{
"href": "https://gw.api.gov.au/dept-xyz/v1/users/ALT-MDFSKFGIFJ86DSF",
"href": "https://gw.api.gov.au/dept-xyz/v1/users/81d13dea-3e03-11ec-8c06-bff381749c44",
"rel": "self"
}
]
Expand All @@ -188,7 +192,7 @@ The client MAY follow the `self` link of each user and figure out all the possib
### Request

```
GET https://gw.api.gov.au/dept-xyz/v1/users/ALT-JFWXHGUV7VI
GET https://gw.api.gov.au/dept-xyz/v1/users/e7c9ad70-3dff-11ec-9d87-6fc27f396179
```

### Response
Expand All @@ -203,22 +207,22 @@ Content-Type: application/json
...
"_links": [
{
"href": "https://gw.api.gov.au/dept-xyz/v1/users/ALT-JFWXHGUV7VI",
"href": "https://gw.api.gov.au/dept-xyz/v1/users/e7c9ad70-3dff-11ec-9d87-6fc27f396179",
"rel": "self",
"method" : "GET"
},
{
"href": "https://gw.api.gov.au/dept-xyz/v1/users/ALT-JFWXHGUV7VI",
"href": "https://gw.api.gov.au/dept-xyz/v1/users/e7c9ad70-3dff-11ec-9d87-6fc27f396179",
"rel": "delete",
"method": "DELETE"
},
{
"href": "https://gw.api.gov.au/dept-xyz/v1/users/ALT-JFWXHGUV7VI",
"href": "https://gw.api.gov.au/dept-xyz/v1/users/e7c9ad70-3dff-11ec-9d87-6fc27f396179",
"rel": "replace",
"method": "PUT"
},
{
"href": "https://gw.api.gov.au/dept-xyz/v1/users/ALT-JFWXHGUV7VI",
"href": "https://gw.api.gov.au/dept-xyz/v1/users/e7c9ad70-3dff-11ec-9d87-6fc27f396179",
"rel": "edit",
"method": "PATCH"
}
Expand All @@ -231,7 +235,7 @@ To delete the user, the client retrieves the URI of the link relation type `dele
### Request

```
DELETE https://gw.api.gov.au/dept-xyz/v1/users/ALT-JFWXHGUV7VI
DELETE https://gw.api.gov.au/dept-xyz/v1/users/e7c9ad70-3dff-11ec-9d87-6fc27f396179

```

Expand Down