-
Notifications
You must be signed in to change notification settings - Fork 11
/
AttachmentService.yaml
255 lines (240 loc) · 9.06 KB
/
AttachmentService.yaml
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
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
openapi: 3.0.3
info:
title: I_Attachment_Service
description: Encrypted email attachments can be sent via this interface
uploaded and made available.
version: 2.3.3
### 2.3.3
# - changed operationId readMaildata
### 2.3.2
# - added distinct definition for header element Content-Length in add_Attachment:
# - Content-Length full request body
# - Content-Length of the actual mail data of the "attachment" form-data in body, which is required in order to check against maxMailSize + performant storage streaming
# - added traceId to Error object
# - changed servers -url
# - changed operationId readAttachment
### 2.3.1
# - added delete_Maildata feature
### 2.3.0
# - changed server url to new api version
# - added response code for wrong input parameters
# - added response type object for operation add_Attachment
### 2.2.0
# - updated url to https://kas.hrst1.kim.telematik/attachments/v2.2/
# - deleted operation read_MaxMailSize
# - changed operation add_Attachment:
# renamed "Shared-Link" to "sharedLink"
# added parameters: expires, recipients, messageID
# added error code 507
# - changed operation read_Attachment:
# added parameter recipient
# added error code 429
### 2.0.0
# - added client authentication for operation add_Attachment
# - changed URI for operations add_attachment and read_attachment
# - added error message strings
# - added HTTP error code 500
### 1.1.0
# - changed data type in operation read_maxMailSize
# - changed error code 405 to 400 in operation add_Attachment
# - changed MIME type multipart/form-data to application/octet-stream in operation add_Attachment() and read_Attachment()
### 1.0.1
# - added errorcode 413 in operation add_Attachment
# - extended URI to interface releases
### 1.0.0
# - initial Version of I_Attachment_Service
externalDocs:
description: GitHub - documentation
url: https://github.com/gematik/api-kim
servers:
- url: /attachments/v2.3/
# Die URL muss wie folgt gebildet werden:
# https://<FQDN gemäß DNS-SD SRV RR>:<Port gemäß DNS-SD SRV RR><Base-path gemäß TXT RR><path gemäß yaml# Datei>
# Die SRV und TXT RR sind unter dem Resource Record Bezeichner <kas_service_name> zu finden.
tags:
- name: Maildata
paths:
/attachment/{attachmentId}:
get:
tags:
- Maildata
summary: Download an attachment
description: returns the attachment encrypted under a share link.
operationId: readMaildata
parameters:
- name: attachmentId
in: path
description: Link reference to the encrypted attachment in the service.
required: true
schema:
type: string
- name: recipient
in: header
description: The recipient's passed email (KIM) address.
required: true
schema:
type: string
format: email
responses:
200:
description: OK
# Attachment was downloaded successfully
content:
application/octet-stream:
schema:
type: string
format: binary
400:
$ref: 'CommonSchemas.yaml#/components/responses/400'
403:
description: Recipient not included in the KIM email recipient list.
content:
application/json; charset=utf-8:
schema:
$ref: 'CommonSchemas.yaml#/components/schemas/Error'
404:
description: Resource not found at the specified link.
content:
application/json; charset=utf-8:
schema:
$ref: 'CommonSchemas.yaml#/components/schemas/Error'
429:
description: Downloaded attachment too many times.
content:
application/json; charset=utf-8:
schema:
$ref: 'CommonSchemas.yaml#/components/schemas/Error'
500:
$ref: 'CommonSchemas.yaml#/components/responses/500'
delete:
tags:
- Maildata
summary: Delete email data from KAS
description: Deletion of email data stored on the KAS, Uri corresponds to sharedLink from add_Attachment.
operationId: deleteMaildata
security:
- KIMBasicAuth: []
# Authentication takes place with username/password from the mail account of the data creator/sender.
parameters:
- name: attachmentId
in: path
description: Link reference to the encrypted attachment in the service.
required: true
schema:
type: string
responses:
200:
description: OK - data has been deleted.
400:
$ref: 'CommonSchemas.yaml#/components/responses/400'
401:
$ref: 'CommonSchemas.yaml#/components/responses/401'
404:
description: Resource not found at the specified link.
content:
application/json; charset=utf-8:
schema:
$ref: 'CommonSchemas.yaml#/components/schemas/Error'
500:
$ref: 'CommonSchemas.yaml#/components/responses/500'
/attachment/:
post:
tags:
- Maildata
summary: Add an attachment
description: An encrypted attachment is added under a newly created sharing link.
operationId: addMaildata
security:
- KIMBasicAuth: []
# Authentication takes place with username/password from the mail account.
parameters:
- name: Content-Length
in: header
description: Total size/length of the request body.
required: true
schema:
type: integer
format: int64
example: 524299123
requestBody:
content:
multipart/form-data:
schema:
type: object
required: [messageID, attachment, recipients, expires]
properties:
messageID:
type: string
description: MessageID of the associated KIM email.
recipients:
type: array
description: List of all recipients (KIM addresses) of the KIM email recipients;
Exactly one address is specified per form part and the form part is
specified multiple times (exploded=true).
# curl e.g.
# -F '[email protected]' \
# -F '[email protected]' \
items:
type: string
format: email
expires:
type: string
description: Time at which the attachment must be deleted.
(Format RFC5322 date-time)
attachment:
type: string
format: binary
description: Contains the encrypted maildata.
encoding:
attachment:
contentType: application/octet-stream
headers:
Content-Length:
required: true
description: Amount of data in bytes of the mail data to be transmitted on the KAS.
schema:
type: integer
format: int64
example: 524288000
Content-Disposition:
required: true
schema:
type: string
example: "Content-Disposition: form-data; name=attachment; filename=attachment.enc"
responses:
201:
description: Created
# The attachment was successfully created under the shared link provided.
content:
application/json; charset=utf-8:
schema:
type: object
properties:
sharedLink:
type: string
# Contains the link to the download point.
# The attachment can be accessed from KAS via the link.
# The link contains the attachmentID - required in operation read_Attachment.
400:
$ref: 'CommonSchemas.yaml#/components/responses/400'
401:
$ref: 'CommonSchemas.yaml#/components/responses/401'
413:
description: Payload Too Large
# The maximum permitted document size has been exceeded.
content:
application/json; charset=utf-8:
schema:
$ref: 'CommonSchemas.yaml#/components/schemas/Error'
500:
$ref: 'CommonSchemas.yaml#/components/responses/500'
507:
description: Not enough memory available.
content:
application/json; charset=utf-8:
schema:
$ref: 'CommonSchemas.yaml#/components/schemas/Error'
components:
securitySchemes:
KIMBasicAuth:
$ref: 'CommonSchemas.yaml#/components/securitySchemes/KIMBasicAuth'