├── LICENSE ├── README.md └── index.md /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2017 Pieter Heyvaert 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # kitsu-tutorial 2 | 3 | The tutorial can be found in `index.md`. 4 | -------------------------------------------------------------------------------- /index.md: -------------------------------------------------------------------------------- 1 | # You and your Kitsu Anime library 2 | 3 | This tutorial guides you through to the core elements of how you can access your [Kitsu](https://kitsu.io) anime library. 4 | We will have a look at the different elements of the [Kitsu API](http://docs.kitsu.apiary.io) and how they can provide you with the data needed to build your application. 5 | 6 | ## Goal 7 | 8 | The goal is to build an application that shows the library entries of a specific user, together with the information about the anime for each entry. Additionally, we provide links to the anime on the Kitsu website. 9 | 10 | ## Focus 11 | 12 | We focus on three elements 13 | 14 | - [users](http://docs.kitsu.apiary.io/#reference/users), 15 | - [libraries](http://docs.kitsu.apiary.io/#reference/user-libraries), and 16 | - [anime series](http://docs.kitsu.apiary.io/#reference/media/anime). 17 | 18 | We are using the latest API available [https://kitsu.io/api/edge/](https://kitsu.io/api/edge/) at the time of writing (09/07/2017). 19 | Note that the tutorial will be about getting the required data from the API and not about how to, e.g., visualize the data. 20 | 21 | ## Steps 22 | 23 | These are the different steps of this tutorial. 24 | 25 | 1. Get the `id` of a user based on his/her `username`. 26 | 2. Get the library entries of a user. 27 | 3. Interpret the information of each library entry. 28 | 4. Get the information about the anime for each entry. 29 | 5. Get the Kitsu website link for each anime. 30 | 31 | ### 1. Get user's `id` 32 | 33 | The `id` of a user can be retreived based on the user's username (referred to as `name`). 34 | The following API GET call gives the details about a user with username ``: 35 | `https://kitsu.io/api/edge/users?filter[name]=` 36 | 37 | What happens here exactly? Well, `https://kitsu.io/api/edge/users` refers to all users. 38 | With `?filter[name]=`, you apply a filter on all users to get only the user with username ``. 39 | Note that you can filter on every element of a `user` object. 40 | 41 | Let's take my username `piehey` as an example. 42 | That would give `https://kitsu.io/api/edge/users?filter[name]=piehey`. 43 | The JSON response of the call looks like this: 44 | 45 | ``` 46 | { 47 | "data": [ 48 | { 49 | "attributes": {...}, 50 | "id": "142706", 51 | "links": {...}, 52 | "relationships": {...}, 53 | "type": "users" 54 | } 55 | ], 56 | "links": {...}, 57 | "meta": { 58 | "count": 1 59 | } 60 | } 61 | ``` 62 | 63 | The `id` of the user can be retreived from the response via `data[0].id`, which is in our example `142706`. 64 | 65 | ### 2. Get library entries of user 66 | 67 | The different library entries of a specific user can be retreived via the user's `id`. The GET call looks like this: `https://kitsu.io/api/edge/users//library-entries`, where `` is the `id` of the user. 68 | 69 | In our example the call looks like `https://kitsu.io/api/edge/users/142706/library-entries`. 70 | The response is 71 | 72 | ``` 73 | { 74 | "data": [ 75 | { 76 | "attributes": {...}, 77 | "id": "17602358", 78 | "links": {...}, 79 | "relationships": { 80 | "anime": {...}, 81 | "drama": {...}, 82 | "manga": {...}, 83 | "media": {...}, 84 | "mediaReaction": {...}, 85 | "nextUnit": {...}, 86 | "review": {...}, 87 | "unit": {...}, 88 | "user": {...} 89 | }, 90 | "type": "libraryEntries" 91 | }, 92 | ... 93 | ], 94 | "links": { 95 | "first": "https://kitsu.io/api/edge/users/142706/library-entries?page%5Blimit%5D=10&page%5Boffset%5D=0", 96 | "last": "https://kitsu.io/api/edge/users/142706/library-entries?page%5Blimit%5D=10&page%5Boffset%5D=30", 97 | "next": "https://kitsu.io/api/edge/users/142706/library-entries?page%5Blimit%5D=10&page%5Boffset%5D=10" 98 | }, 99 | "meta": { 100 | "count": 40 101 | } 102 | } 103 | ``` 104 | 105 | Note that the library entries of a specific user can also be retrieved via `https://kitsu.io/api/edge/library-entries?filter[userId]=` with `` the id of the user. 106 | The object `$.data` of the response contains all the entries. 107 | At the bottom you see that there are 40 entries in total via `$.meta`. 108 | However, only 10 entries are given in this reponse, as the API uses [pagination](http://docs.kitsu.apiary.io/#introduction/json-api/pagination). 109 | The different pages are available via `$.links`. 110 | The next 10 entries are retreived by doing a call to the URL in `$.next`. 111 | The URL has an `offset` of 10, which means that the next page starts with entry 10. 112 | You can customize the number of entries per page via the `limit` property as explained in the [documentation](http://docs.kitsu.apiary.io/#introduction/json-api/pagination). 113 | 114 | ### 3. Interpret the information of each library entry. 115 | Now, let's have a look at a single library entry. 116 | You can find an example below. 117 | 118 | ``` 119 | { 120 | "id": "17641027", 121 | "type": "libraryEntries", 122 | "links": { 123 | "self": "https://kitsu.io/api/edge/library-entries/17641027" 124 | }, 125 | "attributes": { 126 | "createdAt": "2017-07-06T02:41:47.483Z", 127 | "updatedAt": "2017-07-06T02:41:50.879Z", 128 | "status": "current", 129 | "progress": 1, 130 | "volumesOwned": 0, 131 | "reconsuming": false, 132 | "reconsumeCount": 0, 133 | "notes": null, 134 | "private": false, 135 | "progressedAt": "2017-07-06T02:41:50.879Z", 136 | "startedAt": "2017-07-06T02:41:47.483Z", 137 | "finishedAt": null, 138 | "rating": "0.0", 139 | "ratingTwenty": null 140 | }, 141 | "relationships": {...} 142 | } 143 | ``` 144 | 145 | The most interesting information for each entry will probably be in the `attributes` object. 146 | It contains, for example, when an entry was added to the library, when it was finished, and what its rating is. 147 | Note that currently two ratings are available: `rating` and `ratingTwenty`. 148 | The former is deprecated and is being replaced by `ratingTwenty`. 149 | `rating` applies a 0.5/5 system and `ratingTwenty` applies a 2/20 system. 150 | 151 | ### 4. Get the information about the anime for each entry. 152 | If you want to get details about the anime for each entry, you will need to look at the `relationships` object. 153 | A part of this object of our example looks like this. 154 | 155 | ``` 156 | "relationships": { 157 | "user": { 158 | "links": { 159 | "self": "https://kitsu.io/api/edge/library-entries/17641027/relationships/user", 160 | "related": "https://kitsu.io/api/edge/library-entries/17641027/user" 161 | } 162 | }, 163 | "anime": { 164 | "links": { 165 | "self": "https://kitsu.io/api/edge/library-entries/17641027/relationships/anime", 166 | "related": "https://kitsu.io/api/edge/library-entries/17641027/anime" 167 | } 168 | }, 169 | ... 170 | } 171 | ``` 172 | 173 | `user` refers to the user to which this library entry belongs. 174 | `anime` refers to the anime that is part of this entry. 175 | Other relationships are also present, but we wont discuss them here. 176 | More specific, we are focussing on anime, but other media, such as manga can also be part of a library entry. 177 | 178 | The `anime` object has a number of links. 179 | The `self` link refers to the relationship itself, while the `related` link points to the actual anime. 180 | 181 | When we do a GET call to this link, we get the following result. 182 | 183 | ``` 184 | { 185 | "data": { 186 | "id": "12757", 187 | "type": "anime", 188 | "links": { 189 | "self": "https://kitsu.io/api/edge/anime/12757" 190 | }, 191 | "attributes": { 192 | "createdAt": "2016-11-20T07:06:44.960Z", 193 | "updatedAt": "2017-07-08T11:21:51.581Z", 194 | "slug": "netsuzou-trap", 195 | "synopsis": "Yuma and Hotaru have been friends since childhood, so it's only natural that when Yuma is nervous about her new boyfriend, she asks Hotaru for advice. But when Hotaru starts coming onto Yuma for what feels like more than just 'practice', what does it mean...? With boyfriends in the foreground but a secret, passionate tryst in the background, will Yuma and Hotaru try to forget what happened between them or have they fallen into a trap of true love and betrayal?\r\n\r\n(Source: Seven Seas)", 196 | "coverImageTopOffset": 0, 197 | "titles": { 198 | "en": "NTR: Netsuzou Trap", 199 | "en_jp": "Netsuzou TRap", 200 | "ja_jp": "捏造トラップ―NTR―" 201 | }, 202 | "canonicalTitle": "Netsuzou TRap", 203 | "abbreviatedTitles": null, 204 | "averageRating": null, 205 | "ratingFrequencies": {...}, 206 | "userCount": 646, 207 | "favoritesCount": 0, 208 | "startDate": "2017-07-05", 209 | "endDate": null, 210 | "popularityRank": 3460, 211 | "ratingRank": null, 212 | "ageRating": null, 213 | "ageRatingGuide": "", 214 | "subtype": "TV", 215 | "status": "current", 216 | "posterImage": {...}, 217 | "coverImage": null, 218 | "episodeCount": 12, 219 | "episodeLength": 10, 220 | "youtubeVideoId": "3UUs23olVOI", 221 | "showType": "TV", 222 | "nsfw": false 223 | }, 224 | "relationships": {...} 225 | } 226 | } 227 | ``` 228 | 229 | As you can see a lot of information is available, but for now we only want to retreive the title of the anime. 230 | The titles of the anime are available in `data.attributes.canonicalTitle` and `data.attributes.titles`. 231 | The former is the main title: 'Netsuzou TRap'. 232 | The latter provides three additional options. 233 | 234 | ``` 235 | "titles": { 236 | "en": "NTR: Netsuzou Trap", 237 | "en_jp": "Netsuzou TRap", 238 | "ja_jp": "捏造トラップ―NTR―" 239 | } 240 | ``` 241 | 242 | Three titles are available for this specific anime. You can choose between: 243 | 244 | - English - 'NTR: Netsuzou Trap', 245 | - Japanese - '捏造トラップ―NTR―', 246 | - Roumaji - 'Netsuzou TRap'. 247 | 248 | ### 5. Get the Kitsu website link for each anime. 249 | 250 | Finally, we also want to have the Kitsu website link of that anime. 251 | Every Kitsu anime starts with `https://kitsu.io/anime/`. 252 | The slug of an anime has to be added to get the full link. 253 | The slug can be found via `data.attributes.slug`. 254 | For our example, the slug is 'netsuzou-trap', which results in the link `https://kitsu.io/anime/netsuzou-trap`. 255 | 256 | ## Conclusion 257 | 258 | In this tutorial we briefly touched upon a few of the different aspects of the Kitsu API. 259 | More options are available, so make sure to have a look at the documentation. 260 | Furthermore, if you have questions or remarks regarding Kitsu or the Kistu API, be sure to checkout Kitsu's [GitHub](https://github.com/hummingbird-me). 261 | --------------------------------------------------------------------------------