ZeroCrystal's Blog

Back to ZeroCrystal's Blog

Sure! Here's a minimal Python script which creates a Code Verifier, generates an Access Token, saves it locally, and calls an API endpoint: https://gitlab.com/-/snippets/2039434.

As you may have noticed from the guide, there are three possible formats in which your data must be encoded to correctly interact with the API servers. You should focus on identifying the right format for each request you need to carry out to avoid receiving errors messages with usually cryptic or unhelpful descriptions.

‣ URL's query string
A query string is a list of parameters appended to the end of a URL. For example, consider the following string:

https://example.com/endpoint?name=ZeroCrystal&id=5292566

Everything that comes after the question mark forms the query string of the URL, i.e. ?name=ZeroCrystal&id=5292566.

This is the easiest format to understand among the three, and it can be found in many API calls. In the OAuth process, you will have to deal with query strings in Steps 2 and 3.

‣ Form-URL-encoded data
A common approach to send arbitrary data with a POST request is by using the form-URL encoding. In this case, the parameters are encoded using the same format of the query string (e.g. name=ZeroCrystal&id=5292566), but, instead of being appended to the URL, they're written inside the body of the HTTP POST request. The way to accomplish this is language-dependent. Check out the documentation of the library you're using to discover how form-URL-encoded data should be treated.

A common mistake is to send form-URL-encoded parameters as part of the query string rather than inside the body of the request. Make sure to double-check how the data should be sent to the server!

Also, don't forget to add the Content-Type: application/x-www-form-urlencoded HTTP header when sending a POST request containing form-URL-encoded data. Sometimes, it might be ignored by the server, but it's good practice to tell what kind of data you're sending.

The form-URL encoding is used in Steps 4 and 5 of the OAuth procedure.

‣ JSON (JavaScript Object Notation)
The JSON format is well-known and utilised all over the Internet. It is employed as a general-purpose container carrying heterogeneous data. Chances are that the programming language or library you're using is already capable of reading and sending JSON objects.

MAL extensively uses JSON to transfer both simple and complexly structured data between clients and servers. For instance, the Access Token you receive in Step 4 is JSON-encoded.

As with form-URL-encoded data, JSON objects must be included inside the body of a POST request. In this case, you should add a Content-Type: application/json HTTP header.

A final note: some API functions may use two different encodings at the same time. For example, if you want to update your list's status, you have to pass the anime_id as part of the query string, but all other parameters are form-URL-encoded. Always double-check the documentation!

The previous version of the API authenticated users using the HTTP Basic authentication scheme. The username and password were Base64 encoded and sent together with each API request.

This is a terrible choice for two main reasons:

• A user must disclose her private MAL credentials with a third-party developer or organization. You may choose to trust a certain platform, but there's no way to ensure that the credentials won't be misused by the service provider.
  
• All third-party platforms are now attack vectors which can be targeted instead of MAL. If an external platform gets breached, then all the username/password pairs which were stored in its databases could be used by a malicious user to directly access a MyAnimeList account.

OAuth, on the other hand, issues temporary and independent Access Token for each third-party application. In this way, users don't have to share their credentials, and they can also easily revoke access for a specific application.

It is recommended, but not necessary for mobile and native apps. It is required for web applications (excluding browser's userscripts).

The most critical element of an API client is its Client Secret. If you have one, then you must keep it in a safe and private environment (e.g. a web server). Hence, you need some kind of back-end to manage and issue Access Tokens for your users.

Mobile and native apps don't have a Client Secret. It's trivial to obtain an Authorization Code from the device's browser and convert it into an Access Token. However, storing the Access and Refresh Tokens inside the user's device should be considered as a security threat: an adversary may intercept and abuse the Access Token to execute a high amount of API calls that would be deducted from your global pool of requests.

Personally, I would recommend always managing the Access Tokens and API calls in a safe environment, but if you trust your users you can also move all the API logic inside your app's code. Depending on the application's traffic and your technical knowledge, a VPS (Virtual Private Server) might be the right solution. There're tons of platforms offering small VPS for around $5/month.

Alternatively, a serverless infrastructure can be a good choice for applications with a low or medium level of traffic, or if you don't know how to manage a Linux/Windows server (or you don't want to). Platforms like Heroku, Cloudflare Workers, or AWS Lambda let you run custom scripts on-demand when they receive a web request, so you're billed only for the CPU time your programme utilises. This solution is usually cheaper than renting a VPS, and most platforms offer a generous amount of free CPU time.

(Note: I'm not affiliated with any of the platforms quoted above. I decided to list them simply because I used them first-handily, so I believe they're valid suggestions.)

In general, you should not disclose the Access Token to the user. Otherwise, an adversary may intercept the token and abuse it to send a huge amount of API requests, making your application being blocked once it reaches its monthly rate limit.

Personally, I would recommend implementing a simple authorisation mechanism with a custom user-based rate limit, so that a malicious user cannot exploit your global pool of API requests. Read the previous answer for some tips on how you may structure your back-end infrastructure.

On the other hand, if you're sharing your application with a limited number of trusted individuals, then you may choose to send them their respective Access Tokens so that you can write a simpler programme. Either way, it is your responsibility to ensure that the tokens issued by your API clients are used fairly.

The OAuth flow for native and mobile apps is pretty much the same as the one used for web applications. The main difference is the redirect URL.

The IETF best current practice recommends using a private-use URI scheme to redirect the user from the browser's authentication dialogue to your app. For instance, you may register the custom myapp://auth handler to obtain the Authorisation Code from MAL's servers.

Alternatively, some operating systems allow apps to claim "https" scheme URIs in the domains they control. In such cases, when a browser encounters a registered domain, it causes the associated application to be launched instead of regularly loading the web page.

Finally, the loopback interface may be used to retrieve the Authorisation Token. However, keep in mind that using "localhost" or "127.0.0.1" as redirection URLs is the least secure method among these three.

If you need more information, you can read the OAuth 2.0 for Native Apps Best Current Practice.