Skip to content

Commit e2bf49d

Browse files
joakimnordlinglietu
joakimnordling
and
lietu
authored
Add guide for error responses (#36)
* Guide for error responses * Update src/routes/guides/error-responses/+page.svelte Co-authored-by: Janne Enberg <janne.enberg@lietu.net> * Run pre-commit --------- Co-authored-by: Janne Enberg <janne.enberg@lietu.net>
1 parent 31ca110 commit e2bf49d

4 files changed

Lines changed: 135 additions & 0 deletions

File tree

‎src/routes/guides/error-responses/+page.server.ts‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
import IMAGES from "../images.json"
2+
import { GUIDES } from "../urls"
3+
4+
export async function load({ url, route }) {
5+
return {
6+
path: url.pathname,
7+
route: route.id,
8+
guide: GUIDES.ERROR_RESPONSES,
9+
images: IMAGES.ERROR_RESPONSES,
10+
}
11+
}

‎src/routes/guides/error-responses/+page.svelte‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
<script lang="ts">
2+
import SectionTitle from "$lib/components/SectionTitle.svelte"
3+
import Code from "$lib/components/Code.svelte"
4+
import json from "svelte-highlight/languages/json"
5+
import Breadcrumbs from "$lib/components/Breadcrumbs.svelte"
6+
import Title from "$lib/components/Title.svelte"
7+
import TableOfContents from "$lib/components/TableOfContents.svelte"
8+
9+
import type { PageData } from "./$types"
10+
11+
export let data: PageData
12+
</script>
13+
14+
<TableOfContents>
15+
<Title title={data.guide.title} />
16+
17+
<Breadcrumbs path={data.path} />
18+
19+
<p>
20+
The data definitions define the structure for the responses, both for successful responses as
21+
well as for errors. You can check the responses for a particular definition in the OpenAPI Spec
22+
or view it in Swagger UI or ReDoc.
23+
</p>
24+
<p>
25+
Most definitions have just a specific format for the status code <em>200</em> (OK) and use a
26+
shared set of default error message structures for the status codes <em>4xx</em> and
27+
<em>5xx</em>. Most of these error messages share the same structure, which has a <em>type</em>
28+
and <em>message</em> field and look for example like this:
29+
</p>
30+
<Code lang={json}>
31+
{`
32+
{
33+
"type": "not_found",
34+
"message": "The item you requested was not found"
35+
}
36+
`}
37+
</Code>
38+
<p>
39+
This structure applies to the default <em>400</em> (Bad Request), <em>401</em> (Unauthorized),
40+
<em>403</em> (Forbidden), <em>404</em> (Not Found) and <em>500</em> (Internal Server Error) error
41+
status codes, which are the most common ones to be used by a data source, as well as most of the
42+
errors returned by the data sharing service.
43+
</p>
44+
<p>
45+
The identifier in the the <em>type</em> field should be in <em>snake_case</em> (lower case letters
46+
a-z, numbers 0-9 and underscore are allowed) and easily identify the type of error. For example:
47+
</p>
48+
<ul>
49+
<li>
50+
<em>401</em>: <em>api_token_missing_or_invalid</em> if the validation of the API token fails, or
51+
it is missing.
52+
</li>
53+
<li>
54+
<em>403</em>: <em>forbidden</em> if the API token is valid, but the token does not have permission
55+
to request the data specified by the parameters.
56+
</li>
57+
<li>
58+
<em>404</em>: <em>not_found</em> when the requested data can not be found.
59+
</li>
60+
<li>
61+
<em>400</em> & <em>500</em>: Informative and identifiable strings for most other errors, such
62+
as <em>time_range_validation</em> or <em>upstream_error</em>.
63+
</li>
64+
</ul>
65+
<p>
66+
The <em>message</em> field should use a human friendly description.
67+
</p>
68+
69+
<SectionTitle title="Reserved and unsupported status codes" />
70+
71+
<p>
72+
The following status codes are reserved for the use of the IOXIO data sharing service and should
73+
not be sent by a data source:
74+
</p>
75+
<ul>
76+
<li>
77+
<em>444</em> Data source not found, when the <em>?source=</em> query parameter defines a data source
78+
unknown to the data sharing service, in order to distinguish it from when a data source can’t find
79+
data for the given payload and returns a 404 Not Found.
80+
</li>
81+
<li>
82+
<em>502</em> Bad Gateway, when there’s some problem with the connection to or communication with
83+
the data source.
84+
</li>
85+
<li>
86+
<em>503</em> Service Unavailable
87+
</li>
88+
<li>
89+
<em>504</em> Gateway Timeout
90+
</li>
91+
<li>
92+
<em>550</em> Response does not confirm to definition, when the response from the data source either
93+
uses a status code that is not defined for the definition, is a reserved status code, or if the
94+
data returned by the data source does not match the structure defined in the definition.
95+
</li>
96+
</ul>
97+
98+
<SectionTitle title="Other status codes" />
99+
100+
<p>The other status codes present by default in all data definitions are:</p>
101+
<ul>
102+
<li>
103+
<em>422</em> Validation Error is returned by the IOXIO data sharing service when the data in
104+
the request does not match the format specified in the definition. The data source should
105+
likely not encounter data that is invalid as it’s validated by the data sharing service. Data
106+
sources are free to use this, but a generic <em>400</em> error with
107+
<em>"type": "validation_error"</em> with a human friendly description might be a lot easier to
108+
write than generating a response that follows the specified format for this status.
109+
</li>
110+
<li>
111+
<em>429</em> Too many requests, returned by the IOXIO data sharing service when the rate limit
112+
is exceeded. The data source is free to use this as well.
113+
</li>
114+
</ul>
115+
<p>
116+
Each data definition can also define custom status codes and responses for them. For details
117+
about those, please check the definition case by case.
118+
</p>
119+
</TableOfContents>

‎src/routes/guides/images.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -161,6 +161,7 @@
161161
"alt": "Edit group page"
162162
}
163163
},
164+
"ERROR_RESPONSES": {},
164165
"PARTY_CONFIGURATION": {},
165166
"USING_DATA": {
166167
"MENU_DATA_SOURCES": {

‎src/routes/guides/urls.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,10 @@ export const GUIDES = {
2323
title: "Using data from data sources",
2424
href: "/guides/using-data-from-data-sources",
2525
},
26+
ERROR_RESPONSES: {
27+
title: "Error responses",
28+
href: "/guides/error-responses",
29+
},
2630
PARTY_CONFIGURATION: {
2731
title: "Setting up a party configuration domain",
2832
href: "/guides/party-configuration",

0 commit comments

Comments
 (0)