search

open-education-api / specification

OpenAPI (fka Swagger) specification for the Open Education API.
Other
32 stars 26 forks source link

[Change request]: Standardise the 'consumers' mechanisme #292

Open mpdejong opened 1 year ago

mpdejong commented 1 year ago

Organization

Inholland University of Applied Sciences

Project

Implementation OOAPIv5 with RIO consumer

Contact Details

mark.dejong@inholland.nl

Short description

The use of query parameter consumerhas some open interpretations. When multiple consumers are available, can the query parameter request more than one consumerin the result? What is the default behaviour when there is no consumerparameter provided in the request? Will all available consumersbe returned?

When a specific item is requested by id (like GET /programs/{programId}), there is no query parameter available to determine which consumers should be returned in the response.

Version

v5

Usecase

No response

Which institutions support this change?

No response

Proposed solution

No response

Requests and responses

No response

What is your question for the OOAPI work group?

No response

jelmerderonde commented 12 months ago

See also #296:

Right now the consumer query parameter (?consumer=) is only specified on requests that return collections. However, sometimes applications require specific information to function, also for responses that return single objects or for POST/PUT/PATCH requests.

jelmerderonde commented 11 months ago

In een recente meeting is door een leverancier nog een keer aangegeven dat het belang van de consumer query parameter op instance requests echt een must is.

De usecase daar was dat de requirements voor een cursus anders zijn als die voor een nationale of internationale consumer opgevraagd worden. De vraag is nog wel even of het consumer mechanisme de juiste oplossing hiervoor is.

hamrt commented 5 months ago

Keuze is om de aanpassingen op te nemen in een nieuwe branch v 5.1 voor zowel documentatie als voor de spec (toevoegen van query parameter op individuele instances (e.g. programs/{programId}?consumer=rio )

jelmerderonde commented 6 days ago

Suggestion: change the consumers attribute to consumer (change array to just a single object) and make clear that the consumer attribute displays only the consumer information as requested by the consumer= query parameter.

This would also simplify data minimization.