Add API Endpoint documentation

simonspa commented 4 years ago

I have a feature suggestion which would help to integrate this into time tracking. Would it be possible to add an API with endpoints to start and stop a task? With this feature it would e.g. be possible to use an RFID/NFC scanner and swipe a card which automatically starts my work day, and a second swipe stops it.

The card -> Nextcloud user mapping could happen on the client side, which means the RFID terminal would authenticate against the app API with the Nextcloud user and an app token.

te-online commented 4 years ago

Yeah, totally valid feature request! And, good news: there is a REST API! But... It's a bit complicated and it's undocumented. 😂

I'll keep this issue to remind me that I need to write documentation for it.

Generally, the API is maybe not shaped in a way that you think of. It's a sync-API to potentially synchronize client programs, like apps. It uses the concept of commits. As a client you send the latest commit to the API that you know of and any changes that your client holds in a queue, then the API responds with all current data and all updates and deletes after the commit you specified, saves your pending work and sends you back the latest commit. If you don't specify a commit, it will just send you the latest data and commit.

I've implemented it that way for offline work, but never got to finishing the native app...

If you can't wait for the documentation, take a look at these files:

Sorry for this messy state 🤷‍♂️

joleaf commented 3 years ago

Hi, thank you for this work :)

I was also looking for a REST Api for this app :) I need just a list of all my time entries, thought the endpoint might be something like this:

curl -u user:password -X GET 'https://cloud.xyz.de/apps/timemanager/api/items/' -H "OCS-APIRequest: true"

Am I on the right way? :)

te-online commented 3 years ago

@joleaf Almost 😉 Try this instead (you can probably simplify the curl command if you want):

curl --location --request POST 'https://cloud.xyz.de/index.php/apps/timemanager/api/updateObjects' \
-u user:password \
--header 'Content-Type: application/json' \
--data-raw '{
    "data": {
        "clients": {
            "created": [],
            "updated": [],
            "deleted": []
        },
        "projects": {
            "created": [],
            "updated": [],
            "deleted": []
        },
        "tasks": {
            "created": [],
            "updated": [],
            "deleted": []
        },
        "times": {
            "created": [],
            "updated": [],
            "deleted": []
        }
    },
    "lastCommit": ""
}'

I think that's the only way right now. The GET /api/items method was apparently just a test that I never completed. The updateObjects API, however, is designed for programmatic synchronization with a mobile app, that's why it's so verbose. Not proud of this construct, but it should give you what you need. Hope it helps you 😊

joleaf commented 3 years ago

@te-online thank you very much, works for me 👍 So, if I put in a JSON object of an existing entry into "updated", that entry is updated? And the endpoint always returns all entries? :)

PS: Are you planning a mobile app? If not, it's maybe for me a plan for a future project :)

te-online commented 3 years ago

@joleaf Yes, you can update, create or soft-delete records by passing them into the respective arrays. The idea is that your app saves the "commit" (a uuid v4) that it receives from the server when downloading. Then, when you request or update data the next time you include the previous commit in your request. The server will then send you a new commit and only send you the changed data from the commit you sent up until the new commit.

There's a very old Swift project somewhere, but I have to go through it to see if there's some garbage in there before I can make the repository public ;-) However, the app was only designed for landscape view on iPad 🙈 But maybe you can take some inspiration. Once I publish the repo I'll post a new comment here.

te-online commented 3 years ago

@joleaf Here's a public repo of the iOS "app": https://github.com/te-online/te-online--timemanager-ios I'm not sure if it can be used for anything anymore, but it can certainly serve as inspiration :-)

joleaf commented 3 years ago

@te-online Cool :) I started some dart coding with this API :) down sync and up sync already works :)

te-online / timemanager

Add API Endpoint documentation #8