Skip to content

Commit 575a88b

Browse files
oharstaoharsta
authored
Merge pull request #138 from OpenConext/feature/add-opanapi-spec
Add openapi specification of institution information request and response
2 parents df66ffa + 38d7703 commit 575a88b

File tree

2 files changed

+327
-0
lines changed

2 files changed

+327
-0
lines changed

‎src/main/java/aa/aggregators/institution/openapi.json‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
{
2+
"openapi": "3.0.3",
3+
"info": {
4+
"title": "Instelling Attributes API",
5+
"version": "1.0.0",
6+
"description": "API voor het opvragen van attributen op basis van een eduID.\nAuthenticatie gebeurt via HTTP Basic Authentication.\n**Let op:** deze API mag uitsluitend via een beveiligde HTTPS-verbinding worden aangeroepen."
7+
},
8+
"servers": [
9+
{
10+
"url": "https://instelling.tld/api",
11+
"description": "Productieomgeving (alleen HTTPS toegestaan)"
12+
}
13+
],
14+
"paths": {
15+
"/attributes/{eduid}": {
16+
"get": {
17+
"summary": "Haal attributen op voor een gebruiker",
18+
"description": "Retourneert de attributen die gekoppeld zijn aan het opgegeven eduID.\nAlle velden in de response zijn optioneel.\nVereist HTTP Basic Authentication en HTTPS.",
19+
"parameters": [
20+
{
21+
"name": "eduid",
22+
"in": "path",
23+
"required": true,
24+
"description": "Het eduID van de gebruiker (UUID-formaat).",
25+
"schema": {
26+
"type": "string",
27+
"format": "uuid",
28+
"example": "0000-1111-2222-3333"
29+
}
30+
}
31+
],
32+
"security": [
33+
{
34+
"basicAuth": []
35+
}
36+
],
37+
"responses": {
38+
"200": {
39+
"description": "Succesvolle respons met attributen (alle velden optioneel).",
40+
"content": {
41+
"application/json": {
42+
"schema": {
43+
"$ref": "#/components/schemas/UserAttributes"
44+
}
45+
}
46+
}
47+
},
48+
"400": {
49+
"description": "Ongeldige request, bijvoorbeeld verkeerd UUID-formaat.",
50+
"content": {
51+
"application/json": {
52+
"schema": {
53+
"$ref": "#/components/schemas/ErrorResponse"
54+
},
55+
"example": {
56+
"error": "Invalid eduID format"
57+
}
58+
}
59+
}
60+
},
61+
"404": {
62+
"description": "Gebruiker niet gevonden voor het opgegeven eduID.",
63+
"content": {
64+
"application/json": {
65+
"schema": {
66+
"$ref": "#/components/schemas/ErrorResponse"
67+
},
68+
"example": {
69+
"error": "User not found"
70+
}
71+
}
72+
}
73+
},
74+
"401": {
75+
"description": "Authenticatie vereist of ongeldig.",
76+
"content": {
77+
"application/json": {
78+
"schema": {
79+
"$ref": "#/components/schemas/ErrorResponse"
80+
},
81+
"example": {
82+
"error": "Unauthorized"
83+
}
84+
}
85+
}
86+
},
87+
"500": {
88+
"description": "Interne serverfout.",
89+
"content": {
90+
"application/json": {
91+
"schema": {
92+
"$ref": "#/components/schemas/ErrorResponse"
93+
},
94+
"example": {
95+
"error": "Internal server error"
96+
}
97+
}
98+
}
99+
}
100+
}
101+
}
102+
}
103+
},
104+
"components": {
105+
"securitySchemes": {
106+
"basicAuth": {
107+
"type": "http",
108+
"scheme": "basic"
109+
}
110+
},
111+
"schemas": {
112+
"AttributeArray": {
113+
"type": "array",
114+
"items": {
115+
"type": "string"
116+
}
117+
},
118+
"UserAttributes": {
119+
"type": "object",
120+
"description": "Bevat alle mogelijke attributen van een gebruiker. Alle velden zijn optioneel; afwezigheid betekent dat het attribuut niet bekend is.",
121+
"properties": {
122+
"given_name": {
123+
"$ref": "#/components/schemas/AttributeArray",
124+
"example": ["John"]
125+
},
126+
"family_name": {
127+
"$ref": "#/components/schemas/AttributeArray",
128+
"example": ["Doe"]
129+
},
130+
"name": {
131+
"$ref": "#/components/schemas/AttributeArray",
132+
"example": ["Prof.dr. John Doe"]
133+
},
134+
"email": {
135+
"$ref": "#/components/schemas/AttributeArray",
136+
"example": ["[email protected]"]
137+
},
138+
"ou": {
139+
"$ref": "#/components/schemas/AttributeArray",
140+
"example": ["Faculty of Science"]
141+
},
142+
"schac_home_organization": {
143+
"$ref": "#/components/schemas/AttributeArray",
144+
"example": ["university.nl"]
145+
},
146+
"eduperson_scoped_affiliation": {
147+
"$ref": "#/components/schemas/AttributeArray",
148+
"example": ["[email protected]"]
149+
},
150+
"uids": {
151+
"$ref": "#/components/schemas/AttributeArray",
152+
"example": ["jdoe123"]
153+
},
154+
"schac_personal_unique_code": {
155+
"$ref": "#/components/schemas/AttributeArray",
156+
"example": ["S12345678"]
157+
},
158+
"eduperson_principal_name": {
159+
"$ref": "#/components/schemas/AttributeArray",
160+
"example": ["[email protected]"]
161+
},
162+
"eduperson_entitlement": {
163+
"$ref": "#/components/schemas/AttributeArray",
164+
"example": ["urn:x-surfnet:surf.nl:surfdrive:quota:100"]
165+
},
166+
"edumember_is_member_of": {
167+
"$ref": "#/components/schemas/AttributeArray",
168+
"example": ["research-group"]
169+
},
170+
"eckid": {
171+
"$ref": "#/components/schemas/AttributeArray",
172+
"example": ["eck123456"]
173+
}
174+
}
175+
},
176+
"ErrorResponse": {
177+
"type": "object",
178+
"properties": {
179+
"error": {
180+
"type": "string",
181+
"description": "Beschrijving van de foutmelding"
182+
}
183+
},
184+
"required": ["error"]
185+
}
186+
}
187+
},
188+
"security": [
189+
{
190+
"basicAuth": []
191+
}
192+
]
193+
}

‎src/main/java/aa/aggregators/institution/openapi.yaml‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
openapi: 3.0.3
2+
info:
3+
title: Instelling Attributes API
4+
version: 1.0.0
5+
description: |
6+
API voor het opvragen van attributen op basis van een eduID.
7+
Authenticatie gebeurt via HTTP Basic Authentication.
8+
**Let op:** deze API mag uitsluitend via een beveiligde HTTPS-verbinding worden aangeroepen.
9+
servers:
10+
- url: https://instelling.tld/api
11+
description: Productieomgeving (alleen HTTPS toegestaan)
12+
paths:
13+
/attributes/{eduid}:
14+
get:
15+
summary: Haal attributen op voor een gebruiker
16+
description: |
17+
Retourneert de attributen die gekoppeld zijn aan het opgegeven eduID.
18+
Alle velden in de response zijn optioneel.
19+
Vereist HTTP Basic Authentication en HTTPS.
20+
parameters:
21+
- name: eduid
22+
in: path
23+
required: true
24+
description: Het eduID van de gebruiker (UUID-formaat).
25+
schema:
26+
type: string
27+
format: uuid
28+
example: 0000-1111-2222-3333
29+
security:
30+
- basicAuth: []
31+
responses:
32+
'200':
33+
description: Succesvolle respons met attributen (alle velden optioneel).
34+
content:
35+
application/json:
36+
schema:
37+
$ref: '#/components/schemas/UserAttributes'
38+
'400':
39+
description: Ongeldige request, bijvoorbeeld verkeerd UUID-formaat.
40+
content:
41+
application/json:
42+
schema:
43+
$ref: '#/components/schemas/ErrorResponse'
44+
example:
45+
error: "Invalid eduID format"
46+
'404':
47+
description: Gebruiker niet gevonden voor het opgegeven eduID.
48+
content:
49+
application/json:
50+
schema:
51+
$ref: '#/components/schemas/ErrorResponse'
52+
example:
53+
error: "User not found"
54+
'401':
55+
description: Authenticatie vereist of ongeldig.
56+
content:
57+
application/json:
58+
schema:
59+
$ref: '#/components/schemas/ErrorResponse'
60+
example:
61+
error: "Unauthorized"
62+
'500':
63+
description: Interne serverfout.
64+
content:
65+
application/json:
66+
schema:
67+
$ref: '#/components/schemas/ErrorResponse'
68+
example:
69+
error: "Internal server error"
70+
components:
71+
securitySchemes:
72+
basicAuth:
73+
type: http
74+
scheme: basic
75+
schemas:
76+
AttributeArray:
77+
type: array
78+
items:
79+
type: string
80+
UserAttributes:
81+
type: object
82+
description: |
83+
Bevat alle mogelijke attributen van een gebruiker.
84+
Alle velden zijn optioneel; afwezigheid betekent dat het attribuut niet bekend is.
85+
properties:
86+
given_name:
87+
$ref: '#/components/schemas/AttributeArray'
88+
example: ["John"]
89+
family_name:
90+
$ref: '#/components/schemas/AttributeArray'
91+
example: ["Doe"]
92+
name:
93+
$ref: '#/components/schemas/AttributeArray'
94+
example: ["Prof.dr. John Doe"]
95+
email:
96+
$ref: '#/components/schemas/AttributeArray'
97+
example: ["[email protected]"]
98+
ou:
99+
$ref: '#/components/schemas/AttributeArray'
100+
example: ["Faculty of Science"]
101+
schac_home_organization:
102+
$ref: '#/components/schemas/AttributeArray'
103+
example: ["university.nl"]
104+
eduperson_scoped_affiliation:
105+
$ref: '#/components/schemas/AttributeArray'
106+
example: ["[email protected]"]
107+
uids:
108+
$ref: '#/components/schemas/AttributeArray'
109+
example: ["jdoe123"]
110+
schac_personal_unique_code:
111+
$ref: '#/components/schemas/AttributeArray'
112+
example: ["S12345678"]
113+
eduperson_principal_name:
114+
$ref: '#/components/schemas/AttributeArray'
115+
example: ["[email protected]"]
116+
eduperson_entitlement:
117+
$ref: '#/components/schemas/AttributeArray'
118+
example: ["urn:x-surfnet:surf.nl:surfdrive:quota:100"]
119+
edumember_is_member_of:
120+
$ref: '#/components/schemas/AttributeArray'
121+
example: ["research-group"]
122+
eckid:
123+
$ref: '#/components/schemas/AttributeArray'
124+
example: ["eck123456"]
125+
ErrorResponse:
126+
type: object
127+
properties:
128+
error:
129+
type: string
130+
description: Beschrijving van de foutmelding
131+
required:
132+
- error
133+
security:
134+
- basicAuth: []

0 commit comments

Comments
 (0)