View Source JikanEx.Request (JikanEx v0.1.6)

Wrapper functions for the corresponding endpoints.

This does not attempt to rate limit its requests, that could be done naively (through explicit 2 second waits if your application is relatively simple), or by implement a genserver-like queue, see this thread for more ideas.

Each function (other than JikanEx.Request.request/3 and JikanEx.Request.request!/3):

  • accepts:
    • the client as the first argument
    • zero or more required arguments as additional individual arguments
    • (optional) an additional list of URL parts
    • (optional) a map of GET parameters
    • (optional) a keyword list of JikanEx.Request.option
  • has a corresponding bang function. Functions without a bang return {:ok, resp} or {:error, resp}, and raise Tesla.Error (inherited from Tesla) when a connection couldn't be made, when there was a Tesla.Adapter error, or when there was a error decoding the response body. Bang functions raise errors on unsuccessful status codes.

Though functions for each request exist, they're just wrappers for a couple function calls from JikanEx.Url:

# for example, building:
# https://api.jikan.moe/v3/user/nekomata1037/animelist/completed/2?year=2019
alias JikanEx.Request
import JikanEx.Url

client = JikanEx.client()

# Using JikanEx.Url calls
response = "user/nekomata1037/"
|> paths([:animelist, :completed, 2])
|> params(:year, 2019)
|> Request.request!(client)

# same as...
response = Request.user!(client, "nekomata1037", [:animelist, :completed, 2], %{year: 2019})

The response from each function is a map, which includes all the keys which Jikan returned. Additionally, it includes http_headers, http_url and http_status.

A good minority of the Jikan requests don't allow you to pass extra URL parts or GET parameters, but every wrapper function here allows to you to pass a list of paths and a map as optional arguments. This keeps the interface the same for all similar functions.

Using Jikans ETag cache validation:

alias JikanEx.Request

client = JikanEx.client()

response = Request.anime!(client, 1)
etag = %Tesla.Env{headers: response["http_headers"]} |> Tesla.get_header("etag")

# request using Tesla directly
new_response = Tesla.get!(response["http_url"], [headers: [{"If-None-Match", etag}]])
304 = new_response.status

Summary

Functions

Same as anime/5 but returns the response directly. Raises JikanEx.Exception on errors.

Wrapper for the /character/ endpoint. Same interface as anime/5

Same as character/5 but returns the response directly. Raises JikanEx.Exception on errors.

Wrapper for the /club/ endpoint. Same interface as anime/5

Same as club/5 but returns the response directly. Raises JikanEx.Exception on errors.

Same as genre/5 but returns the response directly. Raises JikanEx.Exception on errors.

Wrapper for the /magazine/ endpoint. Same interface as anime/5

Same as magazine/5 but returns the response directly. Raises JikanEx.Exception on errors.

Wrapper for the /manga/ endpoint. Same interface as anime/5

Same as manga/5 but returns the response directly. Raises JikanEx.Exception on errors.

Same as meta/5 but returns the response directly. Raises JikanEx.Exception on errors.

Wrapper for the /person/ endpoint. Same interface as anime/5

Same as person/5 but returns the response directly. Raises JikanEx.Exception on errors.

Wrapper for the /producer/ endpoint. Same interface as anime/5

Same as producer/5 but returns the response directly. Raises JikanEx.Exception on errors.

The base request function for the client - all requests eventually call this. Pass a url (String) and a JikanEx.client/1

Same as request/3, but returns the response directly. Raises JikanEx.Exception on errors.

Same as schedule/5 but returns the response directly. Raises JikanEx.Exception on errors.

Same as search/5 but returns the response directly. Raises JikanEx.Exception on errors.

Wrapper for the /season/, /season/archive/ and /season/later/ endpoints.

Same as season/5 but returns the response directly. Raises JikanEx.Exception on errors.

Same as top/5 but returns the response directly. Raises JikanEx.Exception on errors.

Same as user/5 but returns the response directly. Raises JikanEx.Exception on errors.

Types

http_response()

@type http_response() :: map()

option()

@type option() :: {:headers, Tesla.Env.headers()} | {:opts, Tesla.Env.opts()}

response()

@type response() ::
  http_response() | {:ok, http_response()} | {:error, http_response()}

Functions

anime(client, id, paths \\ [], parameters \\ %{}, opts \\ [])

Wrapper for the /anime/ endpoint.

anime!(client, id, paths \\ [], parameters \\ %{}, opts \\ [])

Same as anime/5 but returns the response directly. Raises JikanEx.Exception on errors.

Example

iex> response = JikanEx.Request.anime!(client, 26165)
iex> response["title"]
"Yuri Kuma Arashi"
iex> response = JikanEx.Request.anime!(client, 11061, [:episodes, 2])
iex> response["http_url"]
"https://api.jikan.moe/v3/anime/11061/episodes/2"

character(client, id, paths \\ [], parameters \\ %{}, opts \\ [])

@spec character(
  Tesla.Client.t(),
  pos_integer(),
  [JikanEx.Url.url()],
  JikanEx.Url.parameters(),
  [
    option()
  ]
) :: response()

Wrapper for the /character/ endpoint. Same interface as anime/5

character!(client, id, paths \\ [], parameters \\ %{}, opts \\ [])

@spec character!(
  Tesla.Client.t(),
  pos_integer(),
  [JikanEx.Url.url()],
  JikanEx.Url.parameters(),
  [
    option()
  ]
) :: response()

Same as character/5 but returns the response directly. Raises JikanEx.Exception on errors.

Example

iex> response = JikanEx.Request.character!(client, 16)
iex> response["name"]
"Edward Wong Hau Pepelu Tivrusky IV"

club(client, id, paths \\ [], parameters \\ %{}, opts \\ [])

Wrapper for the /club/ endpoint. Same interface as anime/5

club!(client, id, paths \\ [], parameters \\ %{}, opts \\ [])

Same as club/5 but returns the response directly. Raises JikanEx.Exception on errors.

Example

iex> response = JikanEx.Request.club!(client, 72940)
iex> response["title"]
"Minna no Uta"

genre(client, paths \\ [], parameters \\ %{}, opts \\ [])

Wrapper for the /genre/ endpoint.

genre!(client, paths \\ [], parameters \\ %{}, opts \\ [])

Same as genre/5 but returns the response directly. Raises JikanEx.Exception on errors.

Example

# first number is the genre ID on MAL, second number is the page
iex> response = JikanEx.Request.genre!(client, [:anime, 8, 2])
iex> response["http_url"]
"https://api.jikan.moe/v3/genre/anime/8/2"

magazine(client, id, paths \\ [], parameters \\ %{}, opts \\ [])

Wrapper for the /magazine/ endpoint. Same interface as anime/5

magazine!(client, id, paths \\ [], parameters \\ %{}, opts \\ [])

@spec magazine!(
  Tesla.Client.t(),
  pos_integer(),
  [JikanEx.Url.url()],
  JikanEx.Url.parameters(),
  [
    option()
  ]
) :: response()

Same as magazine/5 but returns the response directly. Raises JikanEx.Exception on errors.

Example

iex> response = JikanEx.Request.magazine!(client, 21)
iex> response["meta"]["name"]
"Hana to Yume"

manga(client, id, paths \\ [], parameters \\ %{}, opts \\ [])

Wrapper for the /manga/ endpoint. Same interface as anime/5

manga!(client, id, paths \\ [], parameters \\ %{}, opts \\ [])

Same as manga/5 but returns the response directly. Raises JikanEx.Exception on errors.

Example

iex> response = JikanEx.Request.manga!(client, 1, [:characters_staff])
iex> response["characters"] |> List.first() |> Map.get("name")
"Liebert, Anna"

meta(client, paths \\ [], parameters \\ %{}, opts \\ [])

Wrapper for the /meta/ endpoint.

meta!(client, paths \\ [], parameters \\ %{}, opts \\ [])

Same as meta/5 but returns the response directly. Raises JikanEx.Exception on errors.

Example

iex> response = JikanEx.Request.meta!(client, [:requests, :anime, :today])
iex> response["http_url"]
"https://api.jikan.moe/v3/meta/requests/anime/today"

person(client, id, paths \\ [], parameters \\ %{}, opts \\ [])

Wrapper for the /person/ endpoint. Same interface as anime/5

person!(client, id, paths \\ [], parameters \\ %{}, opts \\ [])

Same as person/5 but returns the response directly. Raises JikanEx.Exception on errors.

Example

iex> response = JikanEx.Request.person!(client, 40135)
iex> response["url"]
"https://myanimelist.net/people/40135/Rapparu"

producer(client, id, paths \\ [], parameters \\ %{}, opts \\ [])

Wrapper for the /producer/ endpoint. Same interface as anime/5

producer!(client, id, paths \\ [], parameters \\ %{}, opts \\ [])

@spec producer!(
  Tesla.Client.t(),
  pos_integer(),
  [JikanEx.Url.url()],
  JikanEx.Url.parameters(),
  [
    option()
  ]
) :: response()

Same as producer/5 but returns the response directly. Raises JikanEx.Exception on errors.

Example

iex> response = JikanEx.Request.producer!(client, 2)
iex> response["meta"]["name"]
"Kyoto Animation"

request(url, client, opts \\ [])

@spec request(JikanEx.Url.url(), Tesla.Client.t(), [option()]) :: response()

The base request function for the client - all requests eventually call this. Pass a url (String) and a JikanEx.client/1

Returns {:ok, response} on success and {:error, response} on error, where response is a Map

Example

iex> case JikanEx.Request.request("anime/1", client) do
...>   {:ok, response}
...>     -> response["title"]
...>   {:error, response}
...>     -> response["message"]
...> end
"Cowboy Bebop"

request!(url, client, opts \\ [])

@spec request!(JikanEx.Url.url(), Tesla.Client.t(), [option()]) :: response()

Same as request/3, but returns the response directly. Raises JikanEx.Exception on errors.

iex> JikanEx.Request.request!("anime/1", client) |> Map.get("title")
"Cowboy Bebop: Tengoku no Tobira"

schedule(client, paths \\ [], parameters \\ %{}, opts \\ [])

@spec schedule(Tesla.Client.t(), [JikanEx.Url.url()], JikanEx.Url.parameters(), [
  option()
]) ::
  response()

Wrapper for the /schedule/ endpoint

schedule!(client, paths \\ [], parameters \\ %{}, opts \\ [])

@spec schedule!(Tesla.Client.t(), [JikanEx.Url.url()], JikanEx.Url.parameters(), [
  option()
]) ::
  response()

Same as schedule/5 but returns the response directly. Raises JikanEx.Exception on errors.

Example

iex> response = JikanEx.Request.schedule!(client, [:monday])
iex> response["http_url"]
"https://api.jikan.moe/v3/schedule/monday"

search(client, paths \\ [], parameters \\ %{}, opts \\ [])

Wrapper for the /search/ endpoint.

search!(client, paths \\ [], parameters \\ %{}, opts \\ [])

Same as search/5 but returns the response directly. Raises JikanEx.Exception on errors.

Example

iex> response = JikanEx.Request.search!(client, [:anime], %{:q => "Rakugo Shinjuu", :page => 1})
iex> response["results"] |> List.first() |> Map.get("title")
"Shouwa Genroku Rakugo Shinjuu"

season(client, paths \\ [], parameters \\ %{}, opts \\ [])

Wrapper for the /season/, /season/archive/ and /season/later/ endpoints.

season!(client, paths \\ [], parameters \\ %{}, opts \\ [])

Same as season/5 but returns the response directly. Raises JikanEx.Exception on errors.

Example

iex> response = JikanEx.Request.season!(client, [2020, :winter])
iex> response["http_url"]
"https://api.jikan.moe/v3/season/2020/winter"
iex> response = JikanEx.Request.season!(client, [:later])
iex> response["http_url"]
"https://api.jikan.moe/v3/season/later"

top(client, paths \\ [], parameters \\ %{}, opts \\ [])

Wrapper for the /top/ endpoint.

top!(client, paths \\ [], parameters \\ %{}, opts \\ [])

Same as top/5 but returns the response directly. Raises JikanEx.Exception on errors.

Example

iex> response = JikanEx.Request.top!(client, [:anime, 1, :airing])
iex> response["http_url"]
"https://api.jikan.moe/v3/top/anime/1/airing"

user(client, username, paths \\ [], parameters \\ %{}, opts \\ [])

Wrapper for the /user/ endpoint.

user!(client, username, paths \\ [], parameters \\ %{}, opts \\ [])

Same as user/5 but returns the response directly. Raises JikanEx.Exception on errors.

Examples

iex> response = JikanEx.Request.user!(client, "xinil", [:animelist, :all, 2], %{year: 2019})
iex> response["http_url"]
"https://api.jikan.moe/v3/user/xinil/animelist/all/2?year=2019&"
iex> response = JikanEx.Request.user!(client, "xinil")  # request profile
iex> response["joined"]
"2004-11-05T00:00:00+00:00"
iex> response = JikanEx.Request.user!(client, "xinil", [:friends, 2])
iex> response["http_url"]
"https://api.jikan.moe/v3/user/xinil/friends/2"