FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

Added examples, updated docs for image gallery api endpoints · ucoding/BookStack@402eb84 · GitHub

/ BookStack Public
forked from BookStackApp/BookStack

Commit 402eb84

Browse files
ssddanbrown
committed
Added examples, updated docs for image gallery api endpoints
1 parent 3a808fd commit 402eb84

7 files changed

Lines changed: 145 additions & 5 deletions

File tree

‎app/Http/Controllers/Api/ImageGalleryApiController.php‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -34,8 +34,8 @@ protected function rules(): array
3434
}
3535

3636
/**
37-
* Get a listing of gallery images and drawings in the system.
38-
* Requires visibility of the content they're originally uploaded to.
37+
* Get a listing of images in the system. Includes gallery (page content) images and drawings.
38+
* Requires visibility of the page they're originally uploaded to.
3939
*/
4040
public function list()
4141
{
@@ -50,6 +50,11 @@ public function list()
5050

5151
/**
5252
* Create a new image in the system.
53+
* Since "image" is expected to be a file, this needs to be a 'multipart/form-data' type request.
54+
* The provided "uploaded_to" should be an existing page ID in the system.
55+
* If the "name" parameter is omitted, the filename of the provided image file will be used instead.
56+
* The "type" parameter should be 'gallery' for page content images, and 'drawio' should only be used
57+
* when the file is a PNG file with diagrams.net image data embedded within.
5358
*/
5459
public function create(Request $request)
5560
{
@@ -69,6 +74,10 @@ public function create(Request $request)
6974

7075
/**
7176
* View the details of a single image.
77+
* The "thumbs" response property contains links to scaled variants that BookStack may use in its UI.
78+
* The "content" response property provides HTML and Markdown content, in the format that BookStack
79+
* would typically use by default to add the image in page content, as a convenience.
80+
* Actual image file data is not provided but can be fetched via the "url" response property.
7281
*/
7382
public function read(string $id)
7483
{
@@ -78,7 +87,8 @@ public function read(string $id)
7887
}
7988

8089
/**
81-
* Update an existing image in the system.
90+
* Update the details of an existing image in the system.
91+
* Only allows updating of the image name at this time.
8292
*/
8393
public function update(Request $request, string $id)
8494
{
@@ -94,6 +104,8 @@ public function update(Request $request, string $id)
94104

95105
/**
96106
* Delete an image from the system.
107+
* Will also delete thumbnails for the image.
108+
* Does not check or handle image usage so this could leave pages with broken image references.
97109
*/
98110
public function delete(string $id)
99111
{

‎dev/api/requests/image-gallery-update.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"name": "My updated image name"
3+
}

‎dev/api/responses/image-gallery-create.json‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
{
2+
"name": "cute-cat-image.png",
3+
"path": "\/uploads\/images\/gallery\/2023-03\/cute-cat-image.png",
4+
"url": "https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-03\/cute-cat-image.png",
5+
"type": "gallery",
6+
"uploaded_to": 1,
7+
"created_by": {
8+
"id": 1,
9+
"name": "Admin",
10+
"slug": "admin"
11+
},
12+
"updated_by": {
13+
"id": 1,
14+
"name": "Admin",
15+
"slug": "admin"
16+
},
17+
"updated_at": "2023-03-15 08:17:37",
18+
"created_at": "2023-03-15 08:17:37",
19+
"id": 618,
20+
"thumbs": {
21+
"gallery": "https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-03\/thumbs-150-150\/cute-cat-image.png",
22+
"display": "https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-03\/scaled-1680-\/cute-cat-image.png"
23+
},
24+
"content": {
25+
"html": "<a href=\"https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-03\/cute-cat-image.png\" target=\"_blank\"><img src=\"https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-03\/scaled-1680-\/cute-cat-image.png\" alt=\"cute-cat-image.png\"><\/a>",
26+
"markdown": "![cute-cat-image.png](https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-03\/scaled-1680-\/cute-cat-image.png)"
27+
}
28+
}

‎dev/api/responses/image-gallery-list.json‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
{
2+
"data": [
3+
{
4+
"id": 1,
5+
"name": "My cat scribbles",
6+
"url": "https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-02\/scribbles.jpg",
7+
"path": "\/uploads\/images\/gallery\/2023-02\/scribbles.jpg",
8+
"type": "gallery",
9+
"uploaded_to": 1,
10+
"created_by": 1,
11+
"updated_by": 1,
12+
"created_at": "2023-02-12T16:34:57.000000Z",
13+
"updated_at": "2023-02-12T16:34:57.000000Z"
14+
},
15+
{
16+
"id": 2,
17+
"name": "Drawing-1.png",
18+
"url": "https:\/\/bookstack.example.com\/uploads\/images\/drawio\/2023-02\/drawing-1.png",
19+
"path": "\/uploads\/images\/drawio\/2023-02\/drawing-1.png",
20+
"type": "drawio",
21+
"uploaded_to": 2,
22+
"created_by": 2,
23+
"updated_by": 2,
24+
"created_at": "2023-02-12T16:39:19.000000Z",
25+
"updated_at": "2023-02-12T16:39:19.000000Z"
26+
},
27+
{
28+
"id": 8,
29+
"name": "beans.jpg",
30+
"url": "https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-02\/beans.jpg",
31+
"path": "\/uploads\/images\/gallery\/2023-02\/beans.jpg",
32+
"type": "gallery",
33+
"uploaded_to": 6,
34+
"created_by": 1,
35+
"updated_by": 1,
36+
"created_at": "2023-02-15T19:37:44.000000Z",
37+
"updated_at": "2023-02-15T19:37:44.000000Z"
38+
}
39+
],
40+
"total": 3
41+
}

‎dev/api/responses/image-gallery-read.json‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
{
2+
"id": 618,
3+
"name": "cute-cat-image.png",
4+
"url": "https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-03\/cute-cat-image.png",
5+
"created_at": "2023-03-15 08:17:37",
6+
"updated_at": "2023-03-15 08:17:37",
7+
"created_by": {
8+
"id": 1,
9+
"name": "Admin",
10+
"slug": "admin"
11+
},
12+
"updated_by": {
13+
"id": 1,
14+
"name": "Admin",
15+
"slug": "admin"
16+
},
17+
"path": "\/uploads\/images\/gallery\/2023-03\/cute-cat-image.png",
18+
"type": "gallery",
19+
"uploaded_to": 1,
20+
"thumbs": {
21+
"gallery": "https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-03\/thumbs-150-150\/cute-cat-image.png",
22+
"display": "https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-03\/scaled-1680-\/cute-cat-image.png"
23+
},
24+
"content": {
25+
"html": "<a href=\"https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-03\/cute-cat-image.png\" target=\"_blank\"><img src=\"https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-03\/scaled-1680-\/cute-cat-image.png\" alt=\"cute-cat-image.png\"><\/a>",
26+
"markdown": "![cute-cat-image.png](https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-03\/scaled-1680-\/cute-cat-image.png)"
27+
}
28+
}

‎dev/api/responses/image-gallery-update.json‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
{
2+
"id": 618,
3+
"name": "My updated image name",
4+
"url": "https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-03\/cute-cat-image.png",
5+
"created_at": "2023-03-15 08:17:37",
6+
"updated_at": "2023-03-15 08:24:50",
7+
"created_by": {
8+
"id": 1,
9+
"name": "Admin",
10+
"slug": "admin"
11+
},
12+
"updated_by": {
13+
"id": 1,
14+
"name": "Admin",
15+
"slug": "admin"
16+
},
17+
"path": "\/uploads\/images\/gallery\/2023-03\/cute-cat-image.png",
18+
"type": "gallery",
19+
"uploaded_to": 1,
20+
"thumbs": {
21+
"gallery": "https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-03\/thumbs-150-150\/cute-cat-image.png",
22+
"display": "https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-03\/scaled-1680-\/cute-cat-image.png"
23+
},
24+
"content": {
25+
"html": "<a href=\"https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-03\/cute-cat-image.png\" target=\"_blank\"><img src=\"https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-03\/scaled-1680-\/cute-cat-image.png\" alt=\"My updated image name\"><\/a>",
26+
"markdown": "![My updated image name](https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-03\/scaled-1680-\/cute-cat-image.png)"
27+
}
28+
}

‎resources/views/api-docs/parts/getting-started.blade.php‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,11 @@
1414
HTTP POST calls upon events occurring in BookStack.
1515
</li>
1616
<li>
17-
<a href="https://github.com/BookStackApp/BookStack/blob/master/dev/docs/visual-theme-system.md" target="_blank" rel="noopener noreferrer">Visual Theme System</a> -
17+
<a href="https://github.com/BookStackApp/BookStack/blob/development/dev/docs/visual-theme-system.md" target="_blank" rel="noopener noreferrer">Visual Theme System</a> -
1818
Methods to override views, translations and icons within BookStack.
1919
</li>
2020
<li>
21-
<a href="https://github.com/BookStackApp/BookStack/blob/master/dev/docs/logical-theme-system.md" target="_blank" rel="noopener noreferrer">Logical Theme System</a> -
21+
<a href="https://github.com/BookStackApp/BookStack/blob/development/dev/docs/logical-theme-system.md" target="_blank" rel="noopener noreferrer">Logical Theme System</a> -
2222
Methods to extend back-end functionality within BookStack.
2323
</li>
2424
</ul>

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL