[Personalizer] Rest API review

[slahabar]

Swagger PR: #15699

Design link
https://microsoft.sharepoint.com/:w:/t/personalizr/Ebn16DbDmadPuTMggz8FrzIBAsjvBQ4q1X41xsqVMCzkqA?e=qFDOsV

[mikekistler]

Attending:
@slahabar
@mikekistler
@johanste
@tg-msft

The version should probably be v1.1-preview.2.

JS: Are the authentication protocols all the same here? Yes.

JS: What is the format of the request bodies? Just binary, or is there any specification? There is a definition in the repo.

TG: How is versioning handled for the payload? It is in the payload.

JS: There should be client libraries for C#, Java, JavaScript, Python. This is a PLR requirement. You should be planning for that.

Main customer for these APIs is first party, but will be making available to third parties after.

SL: Should we combine these two operations into one?
Keeping separate endpoints seems better from a resource-oriented perspective.
But thinking of these payloads as messages that are just getting posted to EH ... that's not the case tho.

TG: You should have a default response that describes the error response.
Should be the same error response for all operations.

MK: If no response body, then return 204 rather than 200.

Swashbuckle generates the body as "type: string, format: byte" but it should be "type: string, format: binary".
Might need to hand-edit the generated API def to fix this.

TG: Reiterating that the format of the request body should be documented.

Link to meeting recording

[slahabar]

Addressed the above comments in the PR.
#15699

I updated the api description to indicate that it is for first party use and intended to be used within a SDK. This is our primary use case although it will be available to 3rd customers, they should avoid using it.
@mikekistler @johanste @tg-msft