Accessing the API of https://time.pondersource.com

[michielbdejong]

We have a Prejournal instance running on https://time.pondersource.com to keep track of the timesheet data of Ponder Source team members. It also tracks hours from other teams (m-ld, Muze, EvoluData, etc) if that other team has opened that data up to us.

I created an example account 'example' which we can use for debugging, as follows:

curl -d'["nlnet-timesh:Federated Timesheets","0","100"]' https://example:password123@time.pondersource.com/v1/print-timesheet-json
[
    {
        "id": 1,
        "worker": "ismoil",
        "project": "nlnet-timesh:Federated Timesheets",
        "timestamp_": "2022-09-12 00:00:00",
        "amount": "40",
        "description": ""
    }
]

There's only one entry there so far but we're in the process of loading our real live data onto it. Just need to set up some access control before we do that. ;)

I'll also create users for the other two Tier-2 nodes in the network (https://timeld.org/ and https://timesheet.dev3.evoludata.com/).

[ishifoev]

If you need to import information you can just do something like this you can add worked hours to prejournal

curl -d'["worked-hours", "20 September 2021", "stichting", "Peppol for the Masses", 4]' https://example:password123@time.pondersource.com/v1/worked-hours

[michielbdejong]

@ishifoev actually you don't have to repeat the command name in the POST body when accessing Prejournal over https, so it would be more like:

curl -d'["6 July 2022", "nlnet-timesh", "Federated Timesheets", 4]' https://example:password123@time.pondersource.com/v1/worked-hours

[kroky]

@ishifoev @michielbdejong are we still planning on using unique URI for the entries generated on the source system or we phased out this idea?

[michielbdejong]

I think we could go two ways with that. Say your system is the source system, and you call the worked-hours command on our system.

Option A would be that we keep the API of that command as it is now, and that means when you POST a timesheet entry to our system, our system assigns an id, and returns that in the response body. You need to store that as the "remote id" that your entry got assigned. I think that is the standard process, also when interacting with "Tier 1" systems (that, unlike "Tier 2" systems, are not actively participating in our mesh).

Option B would be a bit fancier, that would mean we add an optional sourceId field to our worked-hours command, and you specify your unique id for it there. @ishifoev I think that's the direction you were thinking in when you mentioned adding "UUIDs", maybe?

[kroky]

I was under the impression that each source system will assign/generate a unique URI (might be UUID, might be just any type of URI, for example wikisuite might use an actual url to the item from the API, like https://timesheet.dev3.evoludata.com/api/trackers/1/items/1) that will be shared with other "Tier 1" systems. This way, other systems won't have to store N+1 source IDs and will also have a reference to the remote item if needed + ability to determine the source system. If we move away from this idea to the source_id idea then I will have to extend wikisuite to handle it. Not sure if you discussed this more in the recent meetings?

[michielbdejong]

Yes sorry, see https://gitter.im/federatedbookkeeping/timesheets?at=62dfe4f30a52264798942401 The response is plain text as you can see, we should probably change that to a JSON response, I created https://github.com/pondersource/prejournal/issues/115 about that. @ishifoev what do you think about it?

[kroky]

Besides the JSON response, is there also a way to update an entry that has already been created? Also, can you show the description of the timesheet entry in the print-timesheet-json endpoint?

[ishifoev]

@kroky if you need to update entry in our system you can update the date, project, amount.

curl -d'["update-entry", "23 August 2021",   "ismoil:test",      2,      worked,    2]' https://example:password123@time.pondersource.com/v1/update-entry

[ishifoev]

@kroky I will add description, we have description in our system we just move it in another table.

[mcalligator]

@michielbdejong and @ishifoev, I've updated the API Definitions Wiki page with an edited reproduction of the content of this thread relating to PreJournal, including a description of the expected data format. As a first draft, it's likely to have inaccuracies, so could you review and correct / augment as necessary? Thanks!

[michielbdejong]

Thanks! I think the part about time.pondersource.com looks accurate so far. @ishifoev can you add documentation for the worked-hours command so EvoluData and M-LD can also push data to it?

[michielbdejong]

Hi @kroky sorry I missed your questions earlier, you wrote:

Besides the JSON response, is there also a way to update an entry that has already been created?

Sorry, we hadn't answered that question yet. Yes, see https://github.com/pondersource/prejournal#usage-timepondersourcecom

Also, can you show the description of the timesheet entry in the print-timesheet-json endpoint?

It's already included, I think?

[ishifoev]

@michielbdejong We have a doc for worked-hours or you would like need to separete API documentation?

[ishifoev]

@michielbdejong not is not included, because we have it in movement table first, for now it is in statement. I just create PR for it.

[kroky]

@ishifoev can you also add the description in the update-entry command? One should be able to edit the description, right? Also, I noticed that the docs says timestamp, project, amount with the second field being the project but the actual code uses second and third params of the command to concatenate as user:project. What is the correct format to update an entry? Is the type parameter here always equal to 'worked'?

[ishifoev]

@kroky I just update you can only project without use username. The worked not need because we used it when import ours, Only if you know id it will be enough to update. About description for now, it is for edit, I think not paste. But I will think about it for update entry.

[ishifoev]

@kroky I think I can add description too for your update, I created PR for it. Will be ready, soon.

[michielbdejong]

That was done, see https://github.com/pondersource/prejournal/blob/a17963076eb3082975b659c52db5e110255bd5a7/tests/ImportTimesheetTest.php#L1027