[OpenAPI] Port the gRPC API calls to the REST API

[netsensei]

Story

I should be able to communicate with all the calls which are currently implemented as gRPC in the new OpenAPI based REST API

Success criteria

Port all the gRPC calls currently defined in the proto/api/v1/person.proto are described as OpenAPI calls:

gRPC	HTTP URI	HTTP METHOD	Parameters	Response
getPerson	api/v1/person/{id}	GET	id	person
getPeople	api/v1/person	GET	page	object with cursor and data containing array of people
suggestPeople	api/v1/person-suggest	GET	query	object with data containing array of people
getOrganization	api/v1/organization/{id}	GET	id	organization
getOrganizations	api/v1/organization	GET	page	object with cursor and datacontaining array of organizations
suggestOrganizations	api/v1/organization-suggest	GET	query	object with datacontaining array of organizations
setPersonOrcidToken	api/v1/person/{id}/orcid-token	PUT	body with orcid_token	person
setPersonRole	api/v1/person/{id}/role	PUT	body with role	person
setPersonSettings	api/v1/person/{id}/settings	PUT	body with settings	person

Implementation suggestion

In order to implement a call:

• Specify the call in api/v1/openapi.yaml
• Run go generate ./...
• Update the Service struct in api/v1/service.go to match the Handler interface

Automatic testing scenario

n/a

Additional information

You may try and check if the call works with Postman

Related issues

• 18

[nicolasfranck]

@netsensei this ticket is already described within #19 so I see no need to split this

[netsensei]

@nicolasfranck #19 is the initial setup and wiring the OpenAPI / Ogen generated code into the router whilst testing with a single, simple API call. Only once that's tackled can we move on completing the implementation of the actual API calls as described in this issue.

[mietcls]

To restructure to OAI service way of working

[nicolasfranck]

So I conclude:

• Every call should be a POST request, even reading calls, or even deleting calls (e.g. https://github.com/ugent-library/oai-service/blob/main/api/v1/openapi.yaml#L76)
• All parameters should be part of the request body, and should be encoded in a JSON object
• The endpoint should be a fixed path, and should NOT contain anything that can be deemed as a parameter, like for example the identifier of a record. e.g. use /api/v1/GetPerson instead of /api/v1/people/:id

[netsensei]

@nicolasfranck That's correct. Please create a table of all the calls you plan to implement with these fields:

• gRPC call
• API URL
• name of the request object w/ a list of fields
• name of the response object w/ a list of fields

[nicolasfranck]

gRPC	HTTP URI	HTTP METHOD	Request body	Response body
getPerson	api/v1/get-person	POST	json object with attribute id (string)	json object of person
getPeople	api/v1/get-people	POST	json object with attribute cursor (string)	json object with cursor and data containing array of Person objects
suggestPeople	api/v1/suggest-people	POST	json object with attribute query (string)	json object with data containing array of people
getOrganization	api/v1/get-organization	POST	json object with attribute id (string)	json object of organization
getOrganizations	api/v1/get-organizations	POST	json object with attribute cursor (string)	json object with cursor and datacontaining array of organization objects
suggestOrganizations	api/v1/suggest-organizations	POST	json object with attribute query (string)	object with datacontaining array of organization objects
setPersonOrcid	api/v1/set-person-orcid	POST	json object with attributes orcid (string) and id (string)	json object of person
setPersonOrcidToken	api/v1/set-person-orcid-token	POST	json body with attributes orcid_token (string) and id (string)	json object of person
setPersonRole	api/v1/set-person-role	POST	json body with attributes role (string) and id (string)	json object of person
setPersonSettings	api/v1/set-person-settings	POST	json body with attributes settings (object) and id (string)	json object of person

[netsensei]

@nicolasfranck Can you also replace the "parameters" and " response" columns with "request" and "response" columns?

Request and Response should list per row:

• the name of the request object
• a list of fields in the request object

The last three can be merged into one of course, in which case it should only accept parameters id, orcid, orcid_token and settings.

Let's keep this explicit: separate calls are okay.

[nicolasfranck]

Feel free to say anything about the paths (e.g. get-person vs person-update-settings feels a bit off)