Change Details

Motivation: We want to stop encoding arguments in the request path, and use query parameters instead. This makes more sense for HTTP (and the various proxy layers we have), and is the only way to properly give an origin URL as argument to the API (%2F and / are indistinguishable in Django's request routing). And this will require changing the whole structure of the API. This meta task lists all other breaking changes we want to include in version 2 of the public API. 1. Use query parameters instead of encoding arguments in the request path 2. No leak of the origin id (use only origin URLs) 3. Use [[ https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html | SWH PIDs ]] whenever possible 4. Compatibility with at least one well-known API specification format ([[ https://swagger.io/docs/specification/about/ | OpenAPI ]], SPARQL, ...) 5. Consistent pagination used across all endpoints 6. Authentication 7. Standardize "batch invocation" of endpoints on multiple objects 8. Consistent results for the same object accessed via different endpoints (e.g. `/revision/<rev>/directory` and `/directory/<dir_id>` do not return the same type of result; one is a superset of the other). 9. Future-proofing, wrt. changes of hash algorithms (currently `sha1_git`) 10. Consider dropping `/revision/log/` (?) (see T2450)

Motivation: We want to stop encoding arguments in the request path, and use query parameters instead. This makes more sense for HTTP (and the various proxy layers we have), and is the only way to properly give an origin URL as argument to the API (%2F and / are indistinguishable in Django's request routing). And this will require changing the whole structure of the API. This meta task lists all other breaking changes we want to include in version 2 of the public API. 1. Use query parameters instead of encoding arguments in the request path 2. No leak of the origin id (use only origin URLs) 3. Use [[ https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html | SWHIDs ]] everywhere 4. Compatibility with at least one well-known API specification format ([[ https://swagger.io/docs/specification/about/ | OpenAPI ]], SPARQL, ...) 5. Consistent pagination used across all endpoints 6. Authentication 7. Standardize "batch invocation" of endpoints on multiple objects 8. Consistent results for the same object accessed via different endpoints (e.g. `/revision/<rev>/directory` and `/directory/<dir_id>` do not return the same type of result; one is a superset of the other). 9. Future-proofing, wrt. changes of hash algorithms (currently `sha1_git`) 10. Consider dropping `/revision/log/` (?) (see T2450)

Motivation: We want to stop encoding arguments in the request path, and use query parameters instead. This makes more sense for HTTP (and the various proxy layers we have), and is the only way to properly give an origin URL as argument to the API (%2F and / are indistinguishable in Django's request routing). And this will require changing the whole structure of the API. This meta task lists all other breaking changes we want to include in version 2 of the public API. 1. Use query parameters instead of encoding arguments in the request path 2. No leak of the origin id (use only origin URLs) 3. Use [[ https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html | SWH PIDs ]] whenever possibleywhere 4. Compatibility with at least one well-known API specification format ([[ https://swagger.io/docs/specification/about/ | OpenAPI ]], SPARQL, ...) 5. Consistent pagination used across all endpoints 6. Authentication 7. Standardize "batch invocation" of endpoints on multiple objects 8. Consistent results for the same object accessed via different endpoints (e.g. `/revision/<rev>/directory` and `/directory/<dir_id>` do not return the same type of result; one is a superset of the other). 9. Future-proofing, wrt. changes of hash algorithms (currently `sha1_git`) 10. Consider dropping `/revision/log/` (?) (see T2450)