Add API

[datenangebot]

Provide access to manipulate tables, columns and rows via api

Adding doc for usage

[gwado]

And if possible with a permissions management in order to have access only in public reading too.

[stefan-niedermann]

Hey @datenangebot - I am interested in writing an Android client and I am wondering whether a public REST API has already been provided (and just not been documented yet)?

[datenangebot]

And if possible with a permissions management in order to have access only in public reading too.

Public sharing is not yet implemented. It is on the roadmap, but is not related to this issue.

[datenangebot]

public REST API

@stefan-niedermann Thanks for your issue comment. It's exactly what I am working on.
Here you can find a preview of the API. Some parts are still missing, will take about a week further...
https://petstore.swagger.io/?url=https://github.com/raw/nextcloud/tables/enh/api/APIv1.yaml#/

All the changes are prepared in a pull request. Feel free to checkout and comment something:
#170

And by the way, having an mobile app for tables will be very interesting!

[stefan-niedermann]

Awesome! I'll have a look at it 🚀

[wbob]

this plugin is fun! I'll call it nextbase :) do you plan on taking row level writes through the API, so it would be in scope of #170 or you'll handle this separately?

[datenangebot]

do you plan on taking row level writes through the API

Yes, I am implementing it at this time... stay tuned.

[stefan-niedermann]

How will we handle API versioning?
The current API version is 1, the currently released app version for NC 25 is 0.3.3.

• Will we have minor API jumps or only major API jumps?
• Will the API version be depending in any sense on the app version?
• How is the API version propagated?
  • In the capabilities endpoint? (Deck app is doing this)
  • As header on each request? (Notes app is doing this)

[datenangebot]

There is the first API version, that will be extended from time to time. The new functions are shipped with the tables app versions. But existing methods will (hopefully) never change. So API v1 will be stable forever.

If we need something new, not just an addition, we create API v2...

Sorry, but what do you mean with "API version propagated"?

[stefan-niedermann]

Thanks for your explanations!

(hopefully) never change.

Sure 😄 😉

So API v1 will be stable forever. If we need something new, not just an addition, we create API v2.

Then how will clients be able to know that they can use the "additions" if there is no minor update of the API version to v1.1?

Sorry, but what do you mean with "API version propagated"?

Well, the API version will change over the time - either backwards compatible (for example by adding new endpoints without touching the existing ones) or incompatible (removing deprecated endpoints or change the way how they work).
Clients may support multiple API versions, but even if they do not, they will need to know which API version the current version of the app supports.

Let's assume you add a new endpoint which allows faster or more specific data access, the client will need to know when it can use it and when it needs to fall back to the older API endpoints.

By "propagating" I mean, that the client needs to know the concrete API version (major and minor), to be able to prevent unexpected responses or notice the user that the support for the currenlty used server app version will be dropped soon.

The server app needs therefore to propagate the current API version for example by appending it as a response header in each request (Notes app does this) or adding this information to the Nextcloud capabilities endpoint (Deck app does this).

Hope I made clear what I mean, but in doubt we can also have a short talk on cloud.nextcloud.com 🙂

[stefan-niedermann]

Actually I would be fine with just providing the Tables App version (0.3.3, 0.4.0 and so on) in the capabilities endpoint, for my personal needs this would be sufficient:

curl "https://username:password@cloud.example.com/ocs/v2.php/cloud/capabilities?format=json" -H 'OCS-APIRequest: true'

{
  "ocs": {
    "meta": {
      "status": "ok",
      "statuscode": 200,
      "message": "OK"
    },
    "data": {
      "version": {
        "major": 25,
        "minor": 0,
        "micro": 5,
        "string": "25.0.5",
        "edition": "",
        "extendedSupport": false
      },
      "capabilities": {
        "deck": {
          "version": "1.8.3",
          "canCreateBoards": true,
          "apiVersions": [
            "1.0",
            "1.1"
          ]
        },
        "notes": {
          "api_version": [
            "0.2",
            "1.3"
          ],
          "version": "4.7.2"
        }
        // ADD TABLES INFORMATION HERE
      }
    }
  }
}

[datenangebot]

Then how will clients be able to know that they can use the "additions" if there is no minor update of the API version to v1.1?

Am I mistaken if I say the client don't need to know that? The developer has to know what endpoints can be used and the mobile app (or whatever) has to define the minimum supported tables version.

Thanks for the explanations. I will have a look if I can easily add the tables api capabilities to the nc API capabilities.

[datenangebot]

Actually I would be fine with just providing the Tables App version (0.3.3, 0.4.0 and so on) in the capabilities endpoint, for my personal needs this would be sufficient:

@stefan-niedermann Could look like this, would that be helpful?

[stefan-niedermann]

Yes, absolutely perfect! And you are right, the app version (0.4.0 in your example) is indeed enough for my needs. The installed flag is confusing though - the entry would not even exist if the app is not installed, no?

[datenangebot]

waiting for #215 before closing this issue