Skip to content

Commit 8319043

Browse files
ildyriad7415
ildyria
and
d7415
authored
Add Oauth + scramble api note (#146)
* add Oauth + scramble api note * Update src/content/post/2024-09-24-v6-scramble.mdx Co-authored-by: Martin Stone <[email protected]> --------- Co-authored-by: Martin Stone <[email protected]>
1 parent cbd1501 commit 8319043

File tree

5 files changed

+167
-0
lines changed

5 files changed

+167
-0
lines changed

‎public/blog/v6/20240924-1.png‎

229 KB
Loading

‎public/blog/v6/20240924-2.png‎

71.4 KB
Loading

‎public/blog/v6/20240924-3.png‎

111 KB
Loading

‎src/content/post/2024-09-24-v6-oauth.mdx‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
publishDate: 2024-09-24T07:44:00Z
3+
author: ildyria
4+
title: 'Bite-size v6: Oauth authentication'
5+
excerpt: Bite-size v6 is a series of small post showing the progress made on the development of the future version of Lychee.
6+
image: /blog/v6/20240924-2.png
7+
category: VueJS
8+
tags:
9+
- lychee
10+
- vuejs
11+
- v6
12+
---
13+
Added first in version 5, it is also now available in version 6. I have not fully tested the code
14+
but I am quite confident it works as expected (as it is literally the same as on version 5).
15+
16+
Furthermore, as the keycloak is making use of the `fa-key` icon, we switched the WebAuthn icon to
17+
`fa-fingerprint` to avoid confusion. Furthermore, with biometrics rolling out such as face-id and
18+
fingerprint readers in WebAuthn authentication devices, it also makes more sense to use this icon
19+
(first one from left to right on the row of icons in the screenshot below).
20+
21+
![Fingerprint](/blog/v6/20240924-3.png)

‎src/content/post/2024-09-24-v6-scramble.mdx‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
publishDate: 2024-09-24T08:00:00Z
3+
author: ildyria
4+
title: 'About Lychee API documentation'
5+
excerpt: With v6 at the horizon, we had to drop the support of Scramble, a library responsible for automated API documentation. We explain here the reasons which motivated such choice.
6+
image: /blog/v6/20240924-1.png
7+
category: VueJS
8+
tags:
9+
- lychee
10+
- api
11+
- scramble
12+
- documentation
13+
- v6
14+
---
15+
16+
[x1ntt](https://github.com/x1ntt) asked the following [question](https://github.com/LycheeOrg/Lychee/discussions/2543#discussioncomment-10733692) and I thought it deserved a visible answer.
17+
18+
> Even without API documentation, **is the v6 version compatible with this API?** I think APIs are very important because I have a need for automated development. Maintaining a good API will lead to the emergence of excellent third-party clients and tools.
19+
20+
In short: **Yes** and **No**.
21+
22+
**Yes** because v6 will provide a legacy api option which can be enabled by setting `LEGACY_API_ENABLED` in your `.env`.
23+
Furthermore, the URL of the legacy API do not change, they stay the same. So no need to change your code, you will just need to set the `.env` variable.
24+
25+
**No**, because v6 will provide a completely upgrade of the API which makes use of a bit more than just POST requests.
26+
It will also support GET, PATCH, DELETE (to get closer to proper REST spec).
27+
28+
29+
30+
### About v4 and v5 documentation
31+
32+
Documentation on v4 and v5 was making use of [dedoc/scramble](https://scramble.dedoc.co/). This extension of Laravel was doing a static analysis of the routes, checking the controllers, the requests objects and the resources files. Using those data it generated a nice interface with readable documentation.
33+
34+
It has been brought to our attention that Scramble is not even working anymore on version 5.5.1 and most likely suffers from an infinite recursion during the serialization of one of the response (out of memory error).
35+
36+
In the spirit of open source, I could try to fix it. However, scramble fails at the following:
37+
38+
- proper software design respecting SOLID architecture ([refusal](https://github.com/dedoc/scramble/pull/91) to have proper design with interface, uses reflections instead to check if some methods are available, and violation of the Liskov substitution principle).
39+
- lack of static analysis such as Phpstan.
40+
41+
As I do not feel comfortable to contribute to such code base, it is an easier decision to drop the scramble component completely.
42+
43+
![No more dedoc/scramble](/blog/v6/20240827-2.png)
44+
45+
Furthermore, with version 6 we are now using [Spatie Data](https://spatie.be/docs/laravel-data/v4/introduction).
46+
This allows us to generate [typescripts definitions](https://spatie.be/docs/typescript-transformer/v2/introduction) from those objects,
47+
and thus ensuring stronger type compatibility between front-end and back-end.
48+
49+
Scramble only support Spatie Data in the pro version, we respect the decision of romalytvynenko, and remove it as we are no longer able to use it anymore.
50+
51+
### About v6
52+
53+
It is likely that I will release version 6 without API documentation at first.
54+
My time is limited and I prefer to focus on adding back the functionalities rather than writing documentations,
55+
especially given that the v1 api will remain available.
56+
57+
And to clarify, this does not mean that there won't be documentation of the API at some point.
58+
As x1ntt says "*Maintaining a good API will lead to the emergence of excellent third-party clients and tools.*"
59+
For this reason I am also exploring other documentation options such as [scribe](https://scribe.knuckles.wtf/).
60+
61+
At the time of writing the list of the **api v2** routes is as follows (and subject to change):
62+
```
63+
GET api/v2/Album ............................................. Gallery\AlbumController@get
64+
POST api/v2/Album ..................................... Gallery\AlbumController@createAlbum
65+
PATCH api/v2/Album ..................................... Gallery\AlbumController@updateAlbum
66+
POST api/v2/Album::cover .................................... Gallery\AlbumController@cover
67+
POST api/v2/Album::delete .................................. Gallery\AlbumController@delete
68+
GET api/v2/Album::getTargetListAlbums ........ Gallery\AlbumController@getTargetListAlbums
69+
POST api/v2/Album::header .................................. Gallery\AlbumController@header
70+
POST api/v2/Album::move ...................................... Gallery\AlbumController@move
71+
PATCH api/v2/Album::rename .................................. Gallery\AlbumController@rename
72+
POST api/v2/Album::transfer .............................. Gallery\AlbumController@transfer
73+
POST api/v2/Album::updateProtectionPolicy .. Gallery\AlbumController@updateProtectionPolicy
74+
GET api/v2/Albums ........................................... Gallery\AlbumsController@get
75+
GET api/v2/Auth::config ......................................... AuthController@getConfig
76+
POST api/v2/Auth::login .............................................. AuthController@login
77+
POST api/v2/Auth::logout ............................................ AuthController@logout
78+
GET api/v2/Auth::rights ................................... AuthController@getGlobalRights
79+
GET api/v2/Auth::user ...................................... AuthController@getCurrentUser
80+
GET api/v2/Diagnostics ................................ Admin\DiagnosticsController@errors
81+
GET api/v2/Diagnostics::config ........................ Admin\DiagnosticsController@config
82+
GET api/v2/Diagnostics::info ............................ Admin\DiagnosticsController@info
83+
GET api/v2/Diagnostics::permissions . Admin\DiagnosticsController@getFullAccessPermissions
84+
GET api/v2/Diagnostics::space .......................... Admin\DiagnosticsController@space
85+
GET api/v2/Gallery::Init ................................ Gallery\ConfigController@getInit
86+
GET api/v2/Gallery::getLayout .................. Gallery\ConfigController@getGalleryLayout
87+
GET api/v2/Gallery::getMapProvider ............... Gallery\ConfigController@getMapProvider
88+
GET api/v2/Gallery::getUploadLimits ............. Gallery\ConfigController@getUploadCOnfig
89+
GET api/v2/Jobs ................................................ Admin\JobsController@list
90+
GET api/v2/LandingPage .................................... LandingPageController@__invoke
91+
GET api/v2/Maintenance::cleaning ........................ Admin\Maintenance\Cleaning@check
92+
POST api/v2/Maintenance::cleaning ........................... Admin\Maintenance\Cleaning@do
93+
GET api/v2/Maintenance::genSizeVariants .......... Admin\Maintenance\GenSizeVariants@check
94+
POST api/v2/Maintenance::genSizeVariants ............. Admin\Maintenance\GenSizeVariants@do
95+
GET api/v2/Maintenance::jobs ............................. Admin\Maintenance\FixJobs@check
96+
POST api/v2/Maintenance::jobs ................................ Admin\Maintenance\FixJobs@do
97+
GET api/v2/Maintenance::missingFileSize ......... Admin\Maintenance\MissingFileSizes@check
98+
POST api/v2/Maintenance::missingFileSize ............ Admin\Maintenance\MissingFileSizes@do
99+
POST api/v2/Maintenance::optimize ........................... Admin\Maintenance\Optimize@do
100+
GET api/v2/Maintenance::tree ............................. Admin\Maintenance\FixTree@check
101+
POST api/v2/Maintenance::tree ................................ Admin\Maintenance\FixTree@do
102+
GET api/v2/Maintenance::update ................................ Admin\UpdateController@get
103+
POST api/v2/Maintenance::update .............................. Admin\UpdateController@check
104+
GET api/v2/Oauth .................................................... OauthController@list
105+
GET api/v2/Photo ............................................. Gallery\PhotoController@get
106+
POST api/v2/Photo .......................................... Gallery\PhotoController@upload
107+
PATCH api/v2/Photo .......................................... Gallery\PhotoController@update
108+
DELETE api/v2/Photo .......................................... Gallery\PhotoController@delete
109+
POST api/v2/Photo::copy ...................................... Gallery\PhotoController@copy
110+
POST api/v2/Photo::fromUrl ................................ Gallery\PhotoController@fromUrl
111+
POST api/v2/Photo::move ...................................... Gallery\PhotoController@move
112+
PATCH api/v2/Photo::rename .................................. Gallery\PhotoController@rename
113+
POST api/v2/Photo::rotate .................................. Gallery\PhotoController@rotate
114+
POST api/v2/Photo::star ...................................... Gallery\PhotoController@star
115+
PATCH api/v2/Photo::tags ...................................... Gallery\PhotoController@tags
116+
POST api/v2/Profile::resetToken .............................. ProfileController@resetToken
117+
POST api/v2/Profile::unsetToken .............................. ProfileController@unsetToken
118+
POST api/v2/Profile::update ...................................... ProfileController@update
119+
GET api/v2/Settings ...................................... Admin\SettingsController@getAll
120+
GET api/v2/Settings::getLanguages .................. Admin\SettingsController@getLanguages
121+
POST api/v2/Settings::setConfigs ...................... Admin\SettingsController@setConfigs
122+
GET api/v2/Sharing ........................................ Gallery\SharingController@list
123+
POST api/v2/Sharing ...................................... Gallery\SharingController@create
124+
POST api/v2/Sharing::delete .............................. Gallery\SharingController@delete
125+
POST api/v2/Sharing::edit .................................. Gallery\SharingController@edit
126+
POST api/v2/TagAlbum ............................... Gallery\AlbumController@createTagAlbum
127+
PATCH api/v2/TagAlbum ............................... Gallery\AlbumController@updateTagAlbum
128+
GET api/v2/UserManagement ............................ Admin\UserManagementController@list
129+
POST api/v2/UserManagement::create .................. Admin\UserManagementController@create
130+
POST api/v2/UserManagement::delete .................. Admin\UserManagementController@delete
131+
POST api/v2/UserManagement::save ...................... Admin\UserManagementController@save
132+
GET api/v2/Users .................................................... UsersController@list
133+
GET api/v2/Users::count ............................................ UsersController@count
134+
GET api/v2/Version ................................................. VersionController@get
135+
GET api/v2/WebAuthn ............................... WebAuthn\WebAuthnManageController@list
136+
PATCH api/v2/WebAuthn ............................... WebAuthn\WebAuthnManageController@edit
137+
POST api/v2/WebAuthn::delete ..................... WebAuthn\WebAuthnManageController@delete
138+
POST api/v2/WebAuthn::login ....... webauthn.login › WebAuthn\WebAuthnLoginController@login
139+
POST api/v2/WebAuthn::login/options webauthn.login.options › WebAuthn\WebAuthnLoginControl…
140+
POST api/v2/WebAuthn::register webauthn.register › WebAuthn\WebAuthnRegisterController@reg…
141+
POST api/v2/WebAuthn::register/options webauthn.register.options › WebAuthn\WebAuthnRegist…
142+
GET auth/{provider}/authenticate ....... oauth-authenticate › OauthController@authenticate
143+
GET auth/{provider}/redirect .................................. OauthController@redirected
144+
GET auth/{provider}/register ................... oauth-register › OauthController@register
145+
```
146+

0 commit comments

Comments
 (0)