Skip to content

Commit 96039ad

Browse files
bradleyboybradleyboy
committed
More albums docs
1 parent e79996b commit 96039ad

File tree

4 files changed

+127
-149
lines changed

4 files changed

+127
-149
lines changed

‎source/includes/_albums.md

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# Albums
2+
3+
## Get all albums
4+
5+
```shell
6+
curl -H "Accepts: application/json" \
7+
http://mysite.com/api.php?/albums
8+
```
9+
10+
Without authentication, this endpoint retrieves all top-level public albums. When authenticated, unlisted albums are also returned. Unless the `flat` parameter is used, only the first level albums will be returned. To get a set's albums, see "Get album contents".
11+
12+
### Endpoint
13+
14+
`GET /albums`
15+
16+
### Query Parameters
17+
18+
Parameter | Default | Description | Valid values
19+
--------- | ------- | ----------- | ------------
20+
day | false | Return albums from a particular day. Requires a valid year and month parameter. | Any valid day. ex: 1
21+
day_not | false | Return albums from all buy one particular day. Requires a valid year and month parameter. | Any valid day. ex: 1
22+
flat | false | Return all albums in the list, regardless of their hierachacal level. | true or false
23+
id_not | false | Exclude albums from the list by id. | Any album ID. Exclude multiple IDs using a comma. Ex: 1,2
24+
include_empty | true | If false, albums containing no content are omitted from the results. | true or false
25+
limit | false | Limit the number of albums to return per page of results. | Any number greater than zero.
26+
listed | true | If false, unlisted albums are retured as well. Requires authorization. | true or false
27+
match_all_tags | false | When using tags or tags_not, whether to look for all of the supplied tags. | true or false
28+
month | false | Return albums from a particular month. Requires a valid year parameter. | Any valid month. ex: 1
29+
month_not | false | Return albums from all buy one particular month. Requires a valid year parameter. | Any valid month. ex: 1
30+
order_by | title | What data is used to sort the returned list. | title, published_on, modified_on, created_on
31+
order_direction | ASC | Whether to sort in ASC or DESC order. | ASC or DESC
32+
page | 1 | See pagination. | Any number from 1 to total_pages.
33+
search | false | String to search by. Search is performed on the album's title, description and tag fields unless search_filter is defined. | Any string
34+
search_filter | false | Limit the fields used in the search. | title, description or tags
35+
tags | false | Search for albums with specific tags. | Any string. Separate multiple tags with a comma.
36+
tags_not | false | Search for albums without specific tags. | Any string. Separate multiple tags with a comma.
37+
types | all | Return only sets or standard albums. | all, set or standard
38+
with_covers | true | Whether or not to return cover data with each album | true or false
39+
year | false | Return albums from a particular year. | Any valid year. ex: 2014
40+
year_not | false | Return albums from all buy one particular year. | Any valid year. ex: 2014
41+
42+
## Get albums tree
43+
44+
```shell
45+
curl -H "Accepts: application/json" \
46+
http://mysite.com/api.php?/albums/tree
47+
```
48+
49+
> Get unlisted tree:
50+
51+
```shell
52+
curl -H "Accepts: application/json" \
53+
-H "X-Koken-Token: your-token-here" \
54+
http://mysite.com/api.php?/albums/tree/listed:0
55+
```
56+
57+
Get hierarchical view of the album tree.
58+
59+
### Endpoint
60+
61+
`GET /albums/tree`
62+
63+
Parameter | Default | Description | Valid values
64+
--------- | ------- | ----------- | ------------
65+
listed | true | Whether to return listed or unlisted album tree (unlisted requires authentication). | true or false
66+
include_empty | true | Whether to return empty albums in the result. | true or false
67+
68+
## Get a specific album
69+
70+
```shell
71+
curl -H "Accepts: application/json" \
72+
http://mysite.com/api.php?/albums/1
73+
```
74+
75+
Get any album by numeric ID or slug.
76+
77+
<aside class="notice">If you attempt to retrive an unlisted album without authentication, this endpoint will return a 403 Forbidden error.</aside>
78+
79+
### Endpoint
80+
81+
`GET /albums/1` or `GET /albums/slug:my-album`
82+
83+
### Query Parameters
84+
85+
Parameter | Default | Description | Valid values
86+
--------- | ------- | ----------- | ------------
87+
neighbors | 2 | How many neigboring albums to load. | Any even number.
88+
include_empty_neighbors | false | Whether to load empty albums when looking for neighboring albums. | true or false
89+
90+
## Get album content
91+
92+
```shell
93+
curl -H "Accepts: application/json" \
94+
http://mysite.com/api.php?/albums/1/content
95+
```
96+
97+
Get any album and its member content (images for a standard album, albums for a set).
98+
99+
<aside class="notice">If you attempt to retrive an unlisted album without authentication, this endpoint will return a 403 Forbidden error.</aside>
100+
101+
### Endpoint
102+
103+
`GET /albums/1/content` or `GET /albums/slug:my-album/content`
104+
105+
### Query Parameters
106+
107+
TODO (only list params that differ from album or content listing)

‎source/includes/_errors.md

Lines changed: 0 additions & 20 deletions
This file was deleted.

‎source/index.md

Lines changed: 19 additions & 128 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ language_tabs:
55
- shell
66

77
includes:
8-
- errors
8+
- albums
99

1010
search: true
1111
---
@@ -14,14 +14,16 @@ search: true
1414

1515
Every installation of Koken exposes an API that can be used to read and write data from that install.
1616

17-
To make a request to the API, you will need the install's API path, which is the domain and path to the Koken installation. For the rest of this document, we'll assume that the API path is:
17+
To make a request to the API, you will need the install's API path, which is the domain and path to the Koken installation. The user of the install will need to supply your application with the appropriate token by logging in to their Koken install and visiting Settings > Applications.
1818

19-
`http://myphotosite.com/koken`
19+
For the rest of this document, we'll assume that the API path is:
20+
21+
`http://mysite.com/`
2022

2123
# Making a request
2224

2325
```shell
24-
curl http://myphotosite.com/koken/api.php?/content
26+
curl http://mysite.com/api.php?/content
2527
```
2628

2729
To make a request, you will need to form the URL to the endpoint using the supplied API path and the endpoint you are wishing to access. To determine the URL to call, think of this psuedo code:
@@ -30,27 +32,26 @@ To make a request, you will need to form the URL to the endpoint using the suppl
3032

3133
For example, to call the `/content` endpoint, the full URL would be:
3234

33-
`http://myphotosite.com/koken/api.php?/content`
35+
`http://mysite.com/api.php?/content`
3436

3537
# Response format
3638

3739
```shell
38-
curl -H "Accept: application/json" http://myphotosite.com/koken/api.php?/content
40+
curl -H "Accept: application/json" \
41+
http://mysite.com/api.php?/content
3942
```
4043

41-
Currently, all Koken API responses return data as JSON. For future proofing, we recommend explicitly passing the `Accept` header.
44+
Currently, all Koken API responses return data as JSON. In the future, Koken may provide other response formats, so we recommend explicitly passing the `Accept` HTTP header.
4245

4346
# Errors
4447

45-
> Accessing an image that does not exist
48+
> Accessing an image that does not exist:
4649
4750
```shell
48-
curl -i -H "Accepts: application/json" http://koken.dev:8888/api.php?/content/2222
51+
curl -i -H "Accepts: application/json" \
52+
http://koken.dev:8888/api.php?/content/2222
4953

5054
HTTP/1.1 404 Not Found
51-
Server: Apache/2.4.7 (Ubuntu)
52-
Content-Length: 95
53-
Content-Type: application/json
5455

5556
{
5657
"request": "/api.php?/content/2222",
@@ -63,12 +64,12 @@ When the Koken API encounters an error, it returns an appropriate HTTP error cod
6364

6465
# Authentication
6566

66-
> To authorize, send the token in a custom HTTP header:
67+
> To authorize, send the token in the X-Koken-Token custom HTTP header:
6768
6869
```shell
6970
curl -H "Accepts: application/json" \
7071
-H "X-Koken-Token: your-token-here" \
71-
http://myphotosite.com/koken/api.php?/content
72+
http://mysite.com/api.php?/content
7273
```
7374

7475
To read public data from a Koken install, authorization is not required. To read unlisted or private information, or to make modifications to content via the API, authorization is required via *tokens*. There are two levels of token permissions:
@@ -98,7 +99,7 @@ The user of the install will need to generate and supply your application with t
9899
99100
```shell
100101
curl -H "Accepts: application/json" \
101-
http://myphotosite.com/koken/api.php?/albums/page:2/limit:10
102+
http://mysite.com/api.php?/albums/page:2/limit:10
102103
```
103104

104105
Any API endpoint that returns a list will also return information that can be used to paginate over that list.
@@ -107,7 +108,7 @@ Any API endpoint that returns a list will also return information that can be us
107108

108109
```shell
109110
curl -H "Accepts: application/json" \
110-
http://myphotosite.com/koken/api.php?/albums/order_by:published_on/order_direction:desc
111+
http://mysite.com/api.php?/albums/order_by:published_on/order_direction:desc
111112
```
112113

113114
Because Koken's entire endpoint is contained in the query string, parameters are passed as key/value pairs in the URL itself. All parameters should be placed at the end of the API URL.
@@ -116,115 +117,5 @@ Because Koken's entire endpoint is contained in the query string, parameters are
116117
117118
```shell
118119
curl -H "Accepts: application/json" \
119-
http://myphotosite.com/koken/api.php?/albums/include_empty:0
120-
```
121-
122-
# Albums
123-
124-
## Get all albums
125-
126-
```shell
127-
curl -H "Accepts: application/json" \
128-
http://myphotosite.com/koken/api.php?/albums
129-
```
130-
131-
> The above command returns JSON structured like this:
132-
133-
```json
134-
[
135-
{
136-
"id": 1,
137-
"name": "Fluffums",
138-
"breed": "calico",
139-
"fluffiness": 6,
140-
"cuteness": 7
141-
},
142-
{
143-
"id": 2,
144-
"name": "Isis",
145-
"breed": "unknown",
146-
"fluffiness": 5,
147-
"cuteness": 10
148-
}
149-
]
150-
```
151-
152-
Without authentication, this endpoint retrieves all public albums. When authenticated, unlisted albums are also returned.
153-
154-
### Endpoint
155-
156-
`GET /albums`
157-
158-
### Query Parameters
159-
160-
Parameter | Default | Description | Valid values
161-
--------- | ------- | ----------- | ------------
162-
day | false | Return albums from a particular day. Requires a valid year and month parameter. | Any valid day. ex: 1
163-
day_not | false | Return albums from all buy one particular day. Requires a valid year and month parameter. | Any valid day. ex: 1
164-
flat | false | Return all albums in the list, regardless of their hierachacal level. | true or false
165-
id_not | false | Exclude albums from the list by id. | Any album ID. Exclude multiple IDs using a comma. Ex: 1,2
166-
include_empty | true | If false, albums containing no content are omitted from the results. | true or false
167-
limit | false | Limit the number of albums to return per page of results. | Any number greater than zero.
168-
listed | true | If false, unlisted albums are retured as well. Requires authorization. | true or false
169-
match_all_tags | false | When using tags or tags_not, whether to look for all of the supplied tags. | true or false
170-
month | false | Return albums from a particular month. Requires a valid year parameter. | Any valid month. ex: 1
171-
month_not | false | Return albums from all buy one particular month. Requires a valid year parameter. | Any valid month. ex: 1
172-
order_by | title | What data is used to sort the returned list. | title, published_on, modified_on, created_on
173-
order_direction | ASC | Whether to sort in ASC or DESC order. | ASC or DESC
174-
page | 1 | See pagination. | Any number from 1 to total_pages.
175-
search | false | String to search by. Search is performed on the album's title, description and tag fields unless search_filter is defined. | Any string
176-
search_filter | false | Limit the fields used in the search. | title, description or tags
177-
tags | false | Search for albums with specific tags. | Any string. Separate multiple tags with a comma.
178-
tags_not | false | Search for albums without specific tags. | Any string. Separate multiple tags with a comma.
179-
types | all | Return only sets or standard albums. | all, set or standard
180-
with_covers | true | Whether or not to return cover data with each album | true or false
181-
year | false | Return albums from a particular year. | Any valid year. ex: 2014
182-
year_not | false | Return albums from all buy one particular year. | Any valid year. ex: 2014
183-
184-
## Get a specific album
185-
186-
```ruby
187-
require 'kittn'
188-
189-
api = Kittn::APIClient.authorize!('meowmeowmeow')
190-
api.kittens.get(2)
191-
```
192-
193-
```python
194-
import 'kittn'
195-
196-
api = Kittn.authorize('meowmeowmeow')
197-
api.kittens.get(2)
198-
```
199-
200-
```shell
201-
curl "http://example.com/api/kittens/3"
202-
-H "Authorization: meowmeowmeow"
203-
```
204-
205-
> The above command returns JSON structured like this:
206-
207-
```json
208-
{
209-
"id": 2,
210-
"name": "Isis",
211-
"breed": "unknown",
212-
"fluffiness": 5,
213-
"cuteness": 10
214-
}
215-
```
216-
217-
This endpoint retrieves a specific kitten.
218-
219-
<aside class="warning">If you're not using an administrator API key, note that some kittens will return 403 Forbidden if they are hidden for admins only.</aside>
220-
221-
### HTTP Request
222-
223-
`GET http://example.com/kittens/<ID>`
224-
225-
### URL Parameters
226-
227-
Parameter | Description
228-
--------- | -----------
229-
ID | The ID of the cat to retrieve
230-
120+
http://mysite.com/api.php?/albums/include_empty:0
121+
```

‎source/stylesheets/screen.css.scss

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -448,7 +448,7 @@ html, body {
448448
background-color: $code-bg;
449449
color: #fff;
450450

451-
padding: 2em $main-padding;
451+
padding: 1em $main-padding;
452452
margin: 0;
453453
width: $examples-width;
454454

0 commit comments

Comments
 (0)