Skip to content
This repository has been archived by the owner on Jun 30, 2021. It is now read-only.

Generic defs #29

Open
wants to merge 6 commits into
base: master
Choose a base branch
from
Open

Generic defs #29

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
cc8397b
document history en aanpassing van de versie van het document.
Jan 9, 2020
e96aaf3
Resolved merge conflict by incorporating both suggestions.
Apr 22, 2020
60d1980
add common paging definitions
Apr 22, 2020
4c9e9fb
Add reusable paging definitions
Apr 22, 2020
7e4a2de
fix typos
Apr 22, 2020
3ca6dec
adding more predefined swagger snippets that can be reused
Jun 18, 2020
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
72 changes: 70 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Digipolis API design & style requirements v6.0.2
# Digipolis API design & style requirements v6.0.4

geldig vanaf 01 mei 2019

Expand Down Expand Up @@ -96,7 +96,9 @@ Versie | Auteur | Datum | Opmerkingen
5.3.0 | Peter Claes | 05/04/2019 | HTTP methode HEAD.
6.0.0 | Tom Sluyts | 11/04/2019 | Wijziging geolocatie standaard naar geospatiale data standaard.
6.0.1 | Peter Claes | 11/04/2019 | Expliciteren 'description'.
6.0.2 | Peter Claes | 28/10/2019 | Verduidelijking paginatie.
6.0.2 | Erik Lenaerts | 26/09/2019 | Aanpak datetime notatie en tijdzones
6.0.3 | Peter Claes | 28/10/2019 | Verduidelijking paginatie.
6.0.4 | Erik Lenaerts | 22/04/2020 | Herbruikbare definities toegevoegd.

## Cheat sheet

Expand Down Expand Up @@ -233,6 +235,8 @@ POST [/\<groepering>]*/\<event> waarbij \<event> eindigt op een voltooid deelwoo
- template : <https://drive.google.com/file/d/0B06myaSd5oKUOEduOHdHRl9RZU0/>
- template met extra info (opm. geen geldige swagger wegens extrainfo) : <https://drive.google.com/file/d/0B06myaSd5oKUWU1samRrODcwUVk/>
- steeds alle descriptions en summaries invullen (in het engels) : routes, parameters, ... : zie ook <https://github.com/digipolisantwerpdocumentation/api-requirements/blob/master/swagger-docs.md>
- generieke swagger definities voor:
- [paging](paging.yaml)
- semantic version opnemen in swagger file

### HTTP verbs
Expand Down Expand Up @@ -930,6 +934,36 @@ Om de paging strategie mee te geven, gebruikt de consumer de optionele parameter
Bij **`withCount`** worden __`Totaal aantal elementen`__ en __`Totaal aantal pagina's`__ altijd verplicht terug gegeven. Bovendien bevat de __`link naar de laatste pagina`__ het paginanummer (zie verder voor een voorbeeld).
Bij **`noCount`** worden de beide totalen niet terug gegeven en is de link naar de laatste pagina een link zonder paginanummer met de vermelding **`last`** (zie verder voor een voorbeeld).

> Om je te helpen hebben we de definitie van **`page`**, **`pagesize`** en **`paging-strategy`** reeds gemaakt voor jou in de [paging.yaml swagger](/components/paging.yaml) file. In onderstaand voorbeeld tonen we hoe je hier gebruik van kan maken:

```JSON
"paths": {
"/invoices": {
"get": {
"summary": "Retrieve a list of invoices",
"description": "Retrieve a paged result list of Sales Invoices",
"parameters": [
{
"$ref": "https://raw.githubusercontent.com/digipolisantwerpdocumentation/api-requirements/components/paging.yaml#/components/parameters/Page"
},
{
"$ref": "https://raw.githubusercontent.com/digipolisantwerpdocumentation/api-requirements/components/paging.yaml#/components/parameters/Pagesize"
},
{
"$ref": "https://raw.githubusercontent.com/digipolisantwerpdocumentation/api-requirements/components/paging.yaml#/components/parameters/PagingStrategy"
}
],
}
}
}
```

Herbruikbare definities van oa. pagingatie parameters vind je terug in de [/components](/components) map hier op GitHub. Om er vanuit jouw swagger file ernaar te refereren kan je volgende link gebruiken:

`https://raw.githubusercontent.com/digipolisantwerpdocumentation/api-requirements/components/paging.yaml#/components/parameters/Page`

Vervang daar waar nodig het deel achter de `#` in deze url.

### Paginatie response bericht

Om paginatie informatie naar de consumer terug te sturen baseren we ons op de HAL specificatie:
Expand Down Expand Up @@ -988,6 +1022,10 @@ Dit alles resulteert in volgende structuur in de response message om pagina link
}
```

**Tip:** Net zoals de **`page`** en **`pagesize`** parameter, hebben we deze **_links** data structuur definitie ook reeds voorgemaakt op:

`https://raw.githubusercontent.com/digipolisantwerpdocumentation/api-requirements/components/paging.yaml#/components/schema/Links`

Bij het ophalen van collections dient bovenstaande structuur steeds aanwezig te zijn in een response message. Dit maakt dat de eigenlijke resources in een wrapper object komen te zitten in het response bericht.
Dit kan door middel van het **\_embedded** reserved keyword. Dit \_embedded object bestaat uit property namen dewelke een link relation
type voorstellen en wiens waarde 1 of meerdere resource objecten zijn.
Expand Down Expand Up @@ -1028,6 +1066,11 @@ Voorbeeld bij `paging-strategy=noCount` :
}
```

**Tip:** Deze **_page** data structuur definitie is reeds voorgemaakt op:

`https://raw.githubusercontent.com/digipolisantwerpdocumentation/api-requirements/components/paging.yaml#/components/schema/Page`


Alle aspecten van paginatie samenvoegend geeft dit volgende response wrapper message voor paginatie:
```json
{
Expand Down Expand Up @@ -1105,6 +1148,31 @@ Geeft als resultaat
}
```

De swagger voor bovenstaand voorbeeld gebruik makende van de generieke definities ziet er als volgt uit:

```JSON
"MyResources": {
"type": "object",
"properties": {
"_links": {
"$ref": "https://raw.githubusercontent.com/digipolisantwerpdocumentation/api-requirements/components/paging.yaml#/components/schema/Links"
},
"_embedded": {
"type": "object",
"properties": {
"business-parties": {
"type": "array",
"items": {
}
}
}
},
"_page": {
"$ref": "https://raw.githubusercontent.com/digipolisantwerpdocumentation/api-requirements/components/paging.yaml#/components/schema/Page"
}

```

Het ophalen van business parties (noCount)

``` prettyprint
Expand Down
110 changes: 110 additions & 0 deletions components/paging.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
openapi: 3.0.1
info:
title: Paging
description: In this OAS document we describe the commonly used Paging parameters
as well as the links & pages schema's
version: 1.0.0
servers:
- url: /
paths: {}
components:
schemas:
Pages:
required:
- number
- size
type: object
properties:
size:
type: integer
description: returns the size of a page provided in the pagesize query parameter
of the request
example: 10
totalElements:
type: integer
description: the total number of items in the resulting collection
example: 34
totalPages:
type: integer
description: the total number of pages in the resulting array. This is calculated
with the given size value
example: 4
number:
type: integer
minimum: 1
description: return the page number provided in the page query parameter
of the request
example: 1
description: A generic model used to describe paging information when requesting
a list of resources.
Links:
type: object
properties:
self:
type: object
properties:
href:
type: string
format: uri
example: https://my-api.digipolis.be/base?pagesize=5&page=2
description: contains a link to this page of this collection
first:
type: object
properties:
href:
type: string
format: uri
example: https://my-api.digipolis.be/base?pagesize=5&page=1
description: contains a link to the first page of this collection
last:
type: object
properties:
href:
type: string
format: uri
example: https://my-api.digipolis.be/base?pagesize=5&page=last
description: contains a link to the last page of this collection
prev:
type: object
properties:
href:
type: string
format: uri
example: https://my-api.digipolis.be/base?pagesize=5&page=1
description: contains a link to the previous page of this collection
next:
type: object
properties:
href:
type: string
format: uri
example: https://my-api.digipolis.be/base?pagesize=5&page=3
description: contains a link to the next page of this collection
description: provides navigational uri's to other pages of the collection
parameters:
Pagesize:
name: pagesize
in: query
description: Max number of items for each page
required: true
schema:
type: integer
PagingStrategy:
name: paging-strategy
in: query
description: Specify the paging strategy, i.e. if totalPages and totalElements
should be included in the response output
schema:
type: string
default: noCount
enum:
- noCount
- withCount
Page:
name: page
in: query
description: Starting offset for the list, this can be either a number or the
literal "last"
required: true
schema:
type: string
109 changes: 109 additions & 0 deletions components/problem.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
openapi: 3.0.1
info:
title: problem types
version: 1.0.0
servers:
- url: /
paths: {}
components:
schemas:
Problem:
type: object
properties:
type:
type: string
description: A URI identifying this problem. The URI should resolve into
human-readable documentation for this problem.
format: uri
example: http://api-gateway/digipolis/payment/v1/payments/FE0032
title:
type: string
description: A short, summary of the problem type. Written in english and
readable for engineers (usually not suited for non technical stakeholders
and not localized)
example: You do not have enough credit.
status:
maximum: 6E+2
exclusiveMaximum: true
minimum: 4E+2
type: integer
description: The HTTP status code generated by the origin server for this
occurrence of the problem.
format: int32
example: 400
identifier:
type: string
description: a unique identifier of the given problem, usefull to recover
this problem message into a logging system.
example: C5C68BE6-B5FF-11E5-B08F-D1D119563991
code:
type: string
description: the code of the given problem
example: FE0032
description: A generic model used to describe problems as a result of incorrect
or failed HTTP requests .
ExtraInfoProblem:
description: Problem with extra information
allOf:
- $ref: '#/components/schemas/Problem'
- type: object
properties:
extraInfo:
type: string
description: extra information regarding the problem
InvalidParamProblem:
description: Problem details for invalid input parameter(s)
allOf:
- $ref: '#/components/schemas/Problem'
- type: object
properties:
invalidParams:
type: array
description: An array of parameter OpenAPI violations
items:
$ref: '#/components/schemas/InvalidParam'
InvalidParam:
type: object
properties:
in:
type: string
description: The location of the invalid parameter (cfr Swagger parameters)
enum:
- body
- path
- query
- header
name:
type: string
description: The name of the invalid parameter
reason:
type: string
description: A message explaining the violation
value:
type: object
description: The value of the erroneous parameter
responses:
BadRequest:
description: Bad request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
Unexpected:
description: Unexpected error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
InternalServer:
description: Internal Server Error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
NotFound:
description: Not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'