owncloud.dev cleanup API - HTTP - LibreGraph (outdated and unmaintained subfolders)

[mmattel]

When looking in owncloud.dev into section API - HTTP - LibreGraph, we find subfolders with static content that is outdated and unmaintained. These are the sections: Spaces, Users and Groups.

Post a discussion with @rhafer and @JanAckermann, we identified that the outdated content could be fully removed and replaced by a link in the libregraph page to the libgregraph api, see image below.

If any api content is missing, it could be added to the swagger page (@rhafer )

[micbar]

what is outdated? i fail to see it in the screenshot.

The libregraph page has more props, but these are way too much.

[mmattel]

what is outdated?

@JanAckermann you can explain best, as you showed it to us 😅

[micbar]

Maybe I explain the idea of owncloud.dev: It should explain what the spec cannot provide. I will always be a subset of the spec.

[AlexAndBear]

@micbar Any documentation page about an api should fully represent the implementation. Therefore a lot of stuff is missing for example in the ,user' service:

• In the attribute section some Entries are missing e.G accountEnabled, appRoleAssignments,memberOf,drive,drives.
• The expand, filter and order query definitions are missing mostly (there is just an expand=memberOf query example). In web we do use much more of these.
• Sections are missing, like tags

So IHMO it makes no sense to have 2 different types of documentation (docs and swagger) which must be in sync to represent the current state of the api.

As a developer, I wouldn't be happy to get a documentation provided with api specs which are kind of outdated and missing to mention most of the possible query attributes.

We need one single point of truth and this should be the swagger Because it's much easier to maintain and keep updated.

Maybe I explain the idea of owncloud.dev: It should explain what the spec cannot provide. I will always be a subset of the spec.

This is not what you would expect on any other project you want to contribute, you would simply expect a good and fully documented Api spec.

[micbar]

This is not what you would expect on any other project you want to contribute, you would simply expect a good and fully documented Api spec.

Yes. The problem is, that Swagger does not explain the concepts and is not good with examples.

[micbar]

People were asking for a more "rich text" page to teach people how to do tasks with the API and understand the basic concepts.

What could we improve to make that better?

[micbar]

Remember, that the audience is not only developers, also integrators and people like admins which want to do something with the apis, e.g. Provisioning users.

[AlexAndBear]

Yes. The problem is, that Swagger does not explain the concepts and is not good with examples. Which concept?

@rhafer Didn't mention about limitation with examples, and there are already some good ones in swagger

Remeber, that the audience is not only developers, also integrators and people like admins which want to do something with the apis, e.g. Provisioning users.

I don't get how an integrator or people like admins benefit from an outdated API spec

[micbar]

I don't get how an integrator or people like admins benefit from an outdated API spec

I don't understand. The spec is in Swagger and always up to date.

[AlexAndBear]

I don't understand. The spec is in Swagger and always up to date.

You was talking about doc apis

[micbar]

So what is the proposal? Less examples in the dev docs?

[AlexAndBear]

Having ONE good api documentation which will represent the current API implementation with examples. Like other projects do as well ^^

For example msGraph

[micbar]

Yes, I understand your intention. But how exactly?

We have a lot of documentation like https://owncloud.dev/apis/http/graph/ which I don't get nicely into swagger.

For example msGraph

MSGraph does not use SwaggerUI, it only has a Rich Content page.

[AlexAndBear]

I have recommended Swagger, because it's less work for the developers (and a lot is documented already), if you feel that the concepts and examples can't be integrated into Swagger, we should keep the API docs and kick Swagger. But this still means, it is super outdated and needs a lot of documentation! Unfortunately, I have the feeling, this can't be done by @mmattel but by the api developers

MSGraph does not use SwaggerUI, it only has a Rich Content page.

I know, I was talking about the single point of truth in general

[micbar]

@dragotin You were doing a lot of work regarding explaining ocis APIs in general. Please throw in your 2 cents.

A lot of stakeholders are interested in the ocis APIS, which are not only LibreGraph but also CS3, webDav, ocs and ocm.

IMO we need to provide different "flight levels".

I think we all can agree that we can improve and that the docs are not "complete"

We need small actionable tasks to be extracted out of this discussion.

[dragotin]

I am with @micbar here. The owncloud.dev docs should explain concepts, high level meaning and usage of APIs, general concepts like authentication, examples and such. After reading it a developer should understand for which purpose and how to use the APIs that we offer with oCIS.

The Swagger based doc adds the current full API spec as a reference.

[AlexAndBear]

I am not too happy with the dev docs and the representation in swagger either way at this stage.

For example, if you have a look at the swaggerUI for updating the user: https://owncloud.dev/libre-graph-api/#/user/UpdateUser

Reading trough New property values/Example Value you will see the memberOf property is defined, which is about group memberships.

So somebody who is reading trough the specs would think they update the memberOf property via this endpoint.

But that can't be done via user PATCH request.

Therefore you need to call other endpoints, same goes for appRoleAssignments

On the other hand, if have a look at the dev docs you won't find any information how to disable the user via the property 'accountEnabled' as this prop is not mentioned.

There is more unfortunately.

For me, the API is not yet well documented and inconsistent.