Skip to content

Commit ec8b32a

Browse files
ulemonsulemons
committed
docs: adding affilaitions api
Signed-off-by: Umberto Sgueglia <usgueglia@contractor.linuxfoundation.org>
1 parent f7ad9b6 commit ec8b32a

1 file changed

Lines changed: 324 additions & 0 deletions

File tree

‎backend/src/api/public/v1/affiliations/openapi.yaml‎

Lines changed: 324 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,324 @@
1+
openapi: 3.1.0
2+
info:
3+
title: LFX Member Organization Affiliations API
4+
version: 1.0.0
5+
description: >
6+
API for querying developer affiliation periods (work experiences) linked to
7+
their verified GitHub identities in the LFX platform.
8+
9+
servers:
10+
- url: /api/v1
11+
description: Production
12+
13+
security:
14+
- ApiKeyAuth: []
15+
16+
paths:
17+
/affiliations:
18+
post:
19+
operationId: getBulkAffiliations
20+
summary: Bulk contributor lookup
21+
description: >
22+
Look up affiliation data for up to 100 GitHub handles in a single
23+
request. Handles that have no matching LFX profile are returned in the
24+
`notFound` array.
25+
tags:
26+
- Affiliations
27+
requestBody:
28+
required: true
29+
content:
30+
application/json:
31+
schema:
32+
type: object
33+
required:
34+
- githubHandles
35+
properties:
36+
githubHandles:
37+
type: array
38+
description: List of GitHub login handles to look up (case-insensitive).
39+
minItems: 1
40+
maxItems: 100
41+
items:
42+
type: string
43+
minLength: 1
44+
example:
45+
- torvalds
46+
- gvanrossum
47+
example:
48+
githubHandles:
49+
- torvalds
50+
- gvanrossum
51+
parameters:
52+
- name: page
53+
in: query
54+
description: Page number (1-based).
55+
required: false
56+
schema:
57+
type: integer
58+
minimum: 1
59+
default: 1
60+
- name: pageSize
61+
in: query
62+
description: Number of contributors to return per page.
63+
required: false
64+
schema:
65+
type: integer
66+
minimum: 1
67+
maximum: 100
68+
default: 20
69+
responses:
70+
'200':
71+
description: Affiliations resolved successfully.
72+
content:
73+
application/json:
74+
schema:
75+
$ref: '#/components/schemas/BulkAffiliationsResponse'
76+
example:
77+
total: 2
78+
totalFound: 2
79+
page: 1
80+
pageSize: 20
81+
contributorsInPage: 2
82+
contributors:
83+
- githubHandle: torvalds
84+
name: Linus Torvalds
85+
emails:
86+
- torvalds@linux-foundation.org
87+
affiliations:
88+
- organization: Linux Foundation
89+
startDate: '2007-01-01'
90+
endDate: null
91+
notFound: []
92+
'400':
93+
$ref: '#/components/responses/BadRequest'
94+
'401':
95+
$ref: '#/components/responses/Unauthorized'
96+
'403':
97+
$ref: '#/components/responses/Forbidden'
98+
'429':
99+
$ref: '#/components/responses/TooManyRequests'
100+
101+
/affiliations/{githubHandle}:
102+
get:
103+
operationId: getAffiliationByHandle
104+
summary: Single contributor lookup
105+
description: >
106+
Convenience endpoint for looking up one developer by GitHub handle.
107+
Useful for debugging and ad-hoc queries.
108+
tags:
109+
- Affiliations
110+
parameters:
111+
- name: githubHandle
112+
in: path
113+
required: true
114+
description: GitHub login handle of the developer (case-insensitive).
115+
schema:
116+
type: string
117+
minLength: 1
118+
example: torvalds
119+
responses:
120+
'200':
121+
description: Developer found.
122+
content:
123+
application/json:
124+
schema:
125+
$ref: '#/components/schemas/Contributor'
126+
example:
127+
githubHandle: torvalds
128+
name: Linus Torvalds
129+
emails:
130+
- torvalds@linux-foundation.org
131+
affiliations:
132+
- organization: Linux Foundation
133+
startDate: '2007-01-01'
134+
endDate: null
135+
'401':
136+
$ref: '#/components/responses/Unauthorized'
137+
'403':
138+
$ref: '#/components/responses/Forbidden'
139+
'404':
140+
description: No LFX profile found for the given GitHub handle.
141+
content:
142+
application/json:
143+
schema:
144+
$ref: '#/components/schemas/HttpError'
145+
example:
146+
error:
147+
code: NOT_FOUND
148+
message: "No LFX profile found for GitHub login 'nonexistent-user'."
149+
'429':
150+
$ref: '#/components/responses/TooManyRequests'
151+
152+
components:
153+
securitySchemes:
154+
ApiKeyAuth:
155+
type: apiKey
156+
in: header
157+
name: Authorization
158+
description: Static API key — pass as `Bearer <token>`.
159+
160+
schemas:
161+
AffiliationPeriod:
162+
type: object
163+
required:
164+
- organization
165+
- startDate
166+
- endDate
167+
properties:
168+
organization:
169+
type: string
170+
description: Name of the organization.
171+
example: Linux Foundation
172+
startDate:
173+
type:
174+
- string
175+
- 'null'
176+
format: date
177+
description: Start date of the affiliation period (ISO 8601).
178+
example: '2020-01-01'
179+
endDate:
180+
type:
181+
- string
182+
- 'null'
183+
format: date
184+
description: End date of the affiliation period, or null if currently active.
185+
example: null
186+
187+
Contributor:
188+
type: object
189+
required:
190+
- githubHandle
191+
- name
192+
- emails
193+
- affiliations
194+
properties:
195+
githubHandle:
196+
type: string
197+
description: Verified GitHub login handle.
198+
example: torvalds
199+
name:
200+
type:
201+
- string
202+
- 'null'
203+
description: Display name from the LFX profile.
204+
example: Linus Torvalds
205+
emails:
206+
type: array
207+
description: Verified email addresses linked to the LFX profile.
208+
items:
209+
type: string
210+
format: email
211+
example:
212+
- torvalds@linux-foundation.org
213+
affiliations:
214+
type: array
215+
description: Resolved affiliation periods, ordered from most recent to oldest (null startDate last).
216+
items:
217+
$ref: '#/components/schemas/AffiliationPeriod'
218+
219+
BulkAffiliationsResponse:
220+
type: object
221+
required:
222+
- total
223+
- totalFound
224+
- page
225+
- pageSize
226+
- contributorsInPage
227+
- contributors
228+
- notFound
229+
properties:
230+
total:
231+
type: integer
232+
description: Total number of handles submitted in the request.
233+
example: 2
234+
totalFound:
235+
type: integer
236+
description: Number of handles that matched an LFX profile.
237+
example: 2
238+
page:
239+
type: integer
240+
description: Current page number.
241+
example: 1
242+
pageSize:
243+
type: integer
244+
description: Maximum contributors per page.
245+
example: 20
246+
contributorsInPage:
247+
type: integer
248+
description: Number of contributors returned in this page.
249+
example: 2
250+
contributors:
251+
type: array
252+
items:
253+
$ref: '#/components/schemas/Contributor'
254+
notFound:
255+
type: array
256+
description: Handles from the request that had no matching LFX profile.
257+
items:
258+
type: string
259+
example: []
260+
261+
HttpError:
262+
type: object
263+
required:
264+
- error
265+
properties:
266+
error:
267+
type: object
268+
required:
269+
- code
270+
- message
271+
properties:
272+
code:
273+
type: string
274+
description: Machine-readable error code.
275+
example: NOT_FOUND
276+
message:
277+
type: string
278+
description: Human-readable error description.
279+
example: Not found
280+
281+
responses:
282+
BadRequest:
283+
description: Invalid request body or query parameters.
284+
content:
285+
application/json:
286+
schema:
287+
$ref: '#/components/schemas/HttpError'
288+
example:
289+
error:
290+
code: BAD_REQUEST
291+
message: "githubHandles: Maximum 100 handles per request"
292+
293+
Unauthorized:
294+
description: Missing or invalid API key.
295+
content:
296+
application/json:
297+
schema:
298+
$ref: '#/components/schemas/HttpError'
299+
example:
300+
error:
301+
code: UNAUTHORIZED
302+
message: Invalid API key
303+
304+
Forbidden:
305+
description: API key does not have the required scope.
306+
content:
307+
application/json:
308+
schema:
309+
$ref: '#/components/schemas/HttpError'
310+
example:
311+
error:
312+
code: INSUFFICIENT_SCOPE
313+
message: Insufficient scope for this operation
314+
315+
TooManyRequests:
316+
description: Rate limit exceeded (60 requests per 60 seconds).
317+
content:
318+
application/json:
319+
schema:
320+
$ref: '#/components/schemas/HttpError'
321+
example:
322+
error:
323+
code: RATE_LIMITED
324+
message: Too many requests, please try again later

0 commit comments

Comments
 (0)