Proper URL support - [closed] #82

Closed alexander-haller closed 2 months ago

In GitLab by @mhxion on Mar 5, 2024, 17:58

Merges improve-url-class -> dev

This PR adds proper URL support for making all kinds of API requests via elAPI. Previously, elAPI only supported the following URL pattern: https://elabftw-dev.uni-heidelberg.de/api/v2/<endpoint name>/<endpoint id>.

This PR adds a ElabFTWURL class that supports a more complete URL. We also introduce the following terms to identify certain parts of a URL.

endpoint_id, sub_endpoint_name, sub_endpoint_id, query are optional. We can pass these parts as arguments to ElabFTWURL, and its get() method will simply convert them to a full URL for us. E.g.,

>>> url = ElabFTWURL(endpoint_name="experiments", experiment_id=17)
>>> url.get()
https://elabftw-dev.uni-heidelberg.de/api/v2/experiments/17
>>> url = ElabFTWURL(endpoint_name="experiments", experiment_id=17, query="{"format": "pdf"}")
>>> url.get()
https://elabftw-dev.uni-heidelberg.de/api/v2/experiments/17?format=pdf

This prepares elAPI for more advanced plugins like the upcoming experiments plugin that uses the sub_endpoint_name and query to download attachments. We can also use query to perform advanced tasks like using the search functionality within eLabFTW.

ElabFTWURL also does a weak validation for the endpoint and sub-endpoint names that are passed.

>>> url = ElabFTWURL(endpoint_name="experiment", experiment_id=17)  # Notice the typo in "experiment" instead of "experiments"
>>> url.get()
ValueError: Endpoint must be one of valid eLabFTW endpoints: ...

Note: eLabFTW uses the terms "entity" and "endpoint" to refer to endpoint_name and "models" to refer to "sub_endpoint_name". I don't think the terms "entity" and "models" make it clear in what they mean. To avoid confusion, I have decided to use generic terms like "endpoint_name" and "sub_endpoint_name".

In GitLab by @mhxion on Mar 5, 2024, 17:58

requested review from @alexander-haller

I love how you create merge requests. They are succinct, contain examples and give context.

approved this merge request

In GitLab by @mhxion on Mar 6, 2024, 24:12

I'm glad you liked it! They also serve as documentations for me. In fact, I meant to use PR details and our discussions here as the basis of documentation (proper documentation) which we currently don't have yet.

In GitLab by @mhxion on Mar 6, 2024, 24:13

Thanks for approving!

In GitLab by @mhxion on Mar 6, 2024, 24:20

Looks like I made a terrible mistake with this branch. I ran a git-filter-repo command from SO without realizing it affects all past commits, and it essentially rewrote every commit. Which is why this branch has 516 commits! It should have less than 10.

Edit: Fixed! At least the remote repo. That was close!

In GitLab by @project_994_bot_1f89ebd5af89f5e987c71c650dd64895 on Mar 6, 2024, 24:40

added 516 commits

00af7ef4...71460b42 - 504 commits from branch dev
71460b42...23a5dfbe - 2 earlier commits
99d7727d - Replace unit_id "''" with None
69be62f3 - Improve FixedAsyncEndpoint; Add FixedEndpoint
0605ff5a - Refactor based on new changes in api and endpoint
c196044a - Fix valid endpoint names
5a31ded2 - Add comment about when sub_unit_id is empty
647f95cf - Rename 'unit_id' to 'endpoint_id'
1f827e8d - Rename 'unit_name' to 'endpoint_name'
100283e5 - Rename 'sub_endpoint' to 'sub_endpoint_name'
b93453e7 - Rename 'endpoint' attribute to 'endpoint_name'
49f6bd24 - Reword 'unit' to 'endpoint'

Compare with previous version

In GitLab by @mhxion on Mar 6, 2024, 03:01

resolved all threads

Tell me how you fixed it so that I learn this! And also sorry that I did not pay notice to the large # of commits when looking over it.

In GitLab by @mhxion on Mar 6, 2024, 16:16

And also sorry that I did not pay notice to the large # of commits when looking over it.

That's totally fine. I myself only noticed it right before when I was trying to merge it and GitLab was showing a merge conflict. And I was like "what conflict?!..." 🤦🏼‍♂️

Tell me how you fixed it so that I learn this!

You're probably going to enjoy my naive process:

git-filter-repo corrupted my entire local repository in directory ~/Workshop/elapi including all local branches and the git stash.
I cloned our remote repo to ~/Workshop/elapi-tmp/. The remote repo's main and dev branches remained unaffected ofc. cded to elapi-temp/.
I recreated the branch improve-url-class (the same name that was on the corrupted branch) from branch dev. This branch was uncorrupted but it didn't have the new commits from the corrupted branch improve-url-class from the corrupted repo.
I followed the steps here to get just the new commits previously made to the corrupted branch.
This improve-url-class branch now remained uncorrupted, without any change in commit history that git-filter-repo rewrote with just the commits I needed. I force pushed this branch. Because the name of the branch was same, GitLab just updated the corrupted improve-url-class branch. The PR showed the correct number of commits. Everything was back to normal.
I moved the good .git folder from ~/Workshop/elapi-tmp/ to ~/Workshop/elapi, so I could keep working on my old local repository where all the virtual envs were.
To get my stash back where I did a week-worth of work, I resorted to PyCharm's "local history". And this is a really awesome feature of PyCharm where it saves almost every single change made in the past just like Git but automatically without having to commit anything. If I had deleted the corrupted directory ~/Workshop/elapi and started fresh I'd have lost this local history from PyCharm. I found another way to get deleted stash back from Git itself, but I never tried it.

In GitLab by @project_994_bot_1f89ebd5af89f5e987c71c650dd64895 on Mar 7, 2024, 03:00

added 12 commits

49f6bd24...8c7a6854 - 2 earlier commits
2674b481 - Replace unit_id "''" with None
9bec6fb2 - Improve FixedAsyncEndpoint; Add FixedEndpoint
503112ca - Refactor based on new changes in api and endpoint
f2e1c7b2 - Fix valid endpoint names
79930045 - Add comment about when sub_unit_id is empty
23922173 - Rename 'unit_id' to 'endpoint_id'
1f79a95c - Rename 'unit_name' to 'endpoint_name'
9393a3db - Rename 'sub_endpoint' to 'sub_endpoint_name'
2e859864 - Rename 'endpoint' attribute to 'endpoint_name'
43976bff - Reword 'unit' to 'endpoint'

Compare with previous version

In GitLab by @project_994_bot_1f89ebd5af89f5e987c71c650dd64895 on Mar 7, 2024, 03:02

added 12 commits

43976bff...161ed892 - 2 earlier commits
f5883af8 - Replace unit_id "''" with None
d547d0cf - Improve FixedAsyncEndpoint; Add FixedEndpoint
cd4444b9 - Refactor based on new changes in api and endpoint
a8a9f31f - Fix valid endpoint names
4f707d33 - Add comment about when sub_unit_id is empty
121b4a1a - Rename 'unit_id' to 'endpoint_id'
4ac2f80d - Rename 'unit_name' to 'endpoint_name'
fd8b2a35 - Rename 'sub_endpoint' to 'sub_endpoint_name'
0f5b4a4a - Rename 'endpoint' attribute to 'endpoint_name'
f9a6e7c4 - Reword 'unit' to 'endpoint'

Compare with previous version

In GitLab by @project_994_bot_1f89ebd5af89f5e987c71c650dd64895 on Mar 7, 2024, 03:03

added 12 commits

f9a6e7c4...1acddd3c - 2 earlier commits
3f7e85f1 - Replace unit_id "''" with None
056730b8 - Improve FixedAsyncEndpoint; Add FixedEndpoint
fcab5bf8 - Refactor based on new changes in api and endpoint
736c40ad - Fix valid endpoint names
094bfe02 - Add comment about when sub_unit_id is empty
2770315f - Rename 'unit_id' to 'endpoint_id'
54a4aac1 - Rename 'unit_name' to 'endpoint_name'
72e0b64d - Rename 'sub_endpoint' to 'sub_endpoint_name'
922cb242 - Rename 'endpoint' attribute to 'endpoint_name'
da824167 - Reword 'unit' to 'endpoint'

Compare with previous version

In GitLab by @mhxion on Mar 22, 2024, 14:14

resolved all threads

In GitLab by @mhxion on Mar 22, 2024, 14:15

This PR had already been merged to https://gitlab.urz.uni-heidelberg.de/urz-elabftw/elapi/-/merge_requests/32. But I guess I never merged the PRs systematically. My bad! This PR can be safely closed now, though the branch is outdated and shouldn't be used.

uhd-urz / elAPI

Proper URL support - [closed] #82