feat: add REST API description #15
Conversation
thomas-fossati
requested review from
cowbon,
deeglaze,
iolivergithub and
jraman567
as code owners
| paths: | ||
| /ratsd/chares: | ||
| post: | ||
| operationId: Ratsd_chares |
There was a problem hiding this comment.
What is chares other than the mythical ferryman? I’m trying to understand if 401 or 403 is the most appropriate error code
There was a problem hiding this comment.
At least for now, it seems sufficient to be successfully authenticated to request evidence using this challenge-response API. I cannot imagine a case where users who have provided an authentication token that checks out aren't also allowed to query this interface. In the future, we may add a 403 to handle such cases but for now 401 looks appropriate to me.
| version: 0.0.1 | ||
| tags: [] | ||
| paths: | ||
| /ratsd/chares: |
There was a problem hiding this comment.
| /ratsd/chares: | |
| /ratsd/chalrsp: |
There was a problem hiding this comment.
An alternative is to use Greek in the URI (/ratsd/Χάρης) and the media type (application/vnd.veraison.Χάρης+json):
POST /ratsd/Χάρης HTTP/1.1
Host: host.example
Authorization: Bearer my.jwt.token
Accept: application/eat+jwt; eat_profile="tag:github.com,2024:veraison/ratsd"
Content-Type: application/vnd.veraison.Χάρης+json
Content-Length: 33
{
"nonce": "MIDBNH28iioisjPy"
}A fun conversation to have with IETF's Internationalization Directorate :-)
| version: 0.0.1 | ||
| tags: [] | ||
| paths: | ||
| /ratsd/chares: |
There was a problem hiding this comment.
I suggest we rename this to a more clear short version as chalrsp
which is more intuitive of what you intend to do.. Personally I struggled with what it means to be a chares?
There was a problem hiding this comment.
Why not challengeReponse in full? ( camelCase or whatever notwithstanding?)
Is this interface only to be used for authentication tokens?
There was a problem hiding this comment.
Is this interface only to be used for authentication tokens?
What do you mean by "authentication tokens"?
There was a problem hiding this comment.
Personally I struggled with what it means to be a chares?
Chares of Lindos, the sculptor of one of the seven wonders of the world!
There was a problem hiding this comment.
Is this interface only to be used for authentication tokens?
What do you mean by "authentication tokens"?
Just referring to an earlier statement. What is expected in the POST body and what is returned?
There was a problem hiding this comment.
What is expected in the POST body and what is returned?
The request body has an application/vnd.veraison.chares+json typed object:
{ "nonce": "base64url_encoded_nonce_" }The request will also sport the auth token in the Authorization header:
Authorization: Bearer my.jwt.tokenThe response is a signed EAT with profile tag:github.com,2024:veraison/ratsd
jraman567
left a comment
jraman567
left a comment
There was a problem hiding this comment.
LGTM. Thank you, @thomas-fossati !
Signed-off-by: Thomas Fossati <[email protected]>
Signed-off-by: Thomas Fossati <[email protected]>
Co-authored-by: Yogesh Deshpande <[email protected]> Signed-off-by: Thomas Fossati <[email protected]>
Co-authored-by: Jag Raman <[email protected]> Signed-off-by: Thomas Fossati <[email protected]>
Fix #14