search

openSUSE / open-build-service

Build and distribute Linux packages from sources in an automatic, consistent and reproducible way #obs
https://openbuildservice.org
GNU General Public License v2.0
938 stars 440 forks source link

Incomplete documentation and proposal to help #11743

Closed why-not-try-calmer closed 1 year ago

why-not-try-calmer commented 3 years ago

Issue Description

The documentation coverage for the api at official documentation is very partial:

Expected Result

100% documentation coverage for api.opensuse.org

Discussion

I understand that api.opensuse.org is mostly consumed in a context where queries and parsing response contents is already taken care of (i.e. osc, zypper). However I think it would be nice to remove this requirement, so that third-party applications know how to consumer it properly.

Now openSUSE/defrag is such a third-party application I am currently working on. As I learn how to send api.opensuse.org well-formed queries, I'd like to document my efforts so as to start fixing the incomplete coverage mentioned above.

For that, however, I'd need some help.

1) Is there a list of the admissible values for these parameters?

2) Is there a list of the expressions (ideally with a description of their syntax) admissible for xpath predicates?

dmarcoux commented 3 years ago

We've been working on an improved version of the API documentation and it's available at https://build.opensuse.org/apidocs-new/. It's not done yet, but we're getting there.

We would love to get your feedback on this. Let us know what you think.

why-not-try-calmer commented 3 years ago

We've been working on an improved version of the API documentation and it's available at https://build.opensuse.org/apidocs-new/. It's not done yet, but we're getting there.

We would love to get your feedback on this. Let us know what you think.

Hi Dany,

Thanks for your quick reply. I can see some nice improvements. I cannot comment much as the "authorize" feature not up yet so cannot really test requests. However flipping through this I think that point (1) in my previous comment is theoretically addressed. Point(2) however remains.

eduardoj commented 1 year ago

We've been working on an improved version of the API documentation and it's available at https://build.opensuse.org/apidocs-new/. It's not done yet, but we're getting there. We would love to get your feedback on this. Let us know what you think.

Hi Dany,

Thanks for your quick reply. I can see some nice improvements. I cannot comment much as the "authorize" feature not up yet so cannot really test requests. However flipping through this I think that point (1) in my previous comment is theoretically addressed. Point(2) however remains.

Hi @why-not-try-calmer!

Time has passed, sorry for the late response.

The good news is that the OpenAPI specification for the OBS got released: https://openbuildservice.org/2023/06/06/openapi-documentation/

Point 2) of your message got addressed a while ago: https://openbuildservice.org/2022/08/29/api-docs-search/

I close the issue. Please feel free to reopen if you find something is missing.