search

Chocobozzz / PeerTube

ActivityPub-federated video streaming platform using P2P directly in your web browser
https://joinpeertube.org/
GNU Affero General Public License v3.0
13.09k stars 1.51k forks source link

Dereference error type field in REST API documentation #6421

Open Schoumi opened 5 months ago

Schoumi commented 5 months ago

Describe the current behavior

The documentation says that code and error in JSON errors are now deprectated and replaced by type and details. I'm not sure why you come to change type to an URL that leads nowhere (no documentation in the end) who is less clearer and parsable than code. 

{
"type":"https://docs.joinpeertube.org/api-rest-reference.html#section/Errors/missing_two_factor",
"detail":"Missing two factor header",
"status":401,
"docs":"https://docs.joinpeertube.org/api-rest-reference.html#operation/getOAuthToken",
"code":"missing_two_factor",
"error":"Missing two factor header"
}

Steps to reproduce

No response

Describe the expected behavior

It's easier for client apps to make some treatment based on code than type now. if you really want to go to URI something like: "error://peertube/auth/missing_two_factor" will be better than we have now. We get that the error is from peertube, about auth. If you don't go to separate error code in sub sections i'm not sure the type improve anything.

Additional information

No response

Chocobozzz commented 5 months ago

Hi,

We try to follow https://datatracker.ietf.org/doc/html/rfc7807#section-3.1, it's the reason why it's an URI.

But it would be better to update the documentation so the type can be correctly dereferenced.

We'll keep code field as I agree it's easier to parse (https://github.com/Chocobozzz/PeerTube/commit/da7ccbb44a469633af987a584392b87f8a01d26e)