Skip to content

Latest commit

 

History

History
113 lines (66 loc) · 6.02 KB

setup.md

File metadata and controls

113 lines (66 loc) · 6.02 KB

Installation

Mal4J requires at least Java 8. No additional dependencies/libraries are required.

Compiled binaries can be installed from:

API setup

1. Create new Client ID

2. Register application

  • Fill in all required fields and App Redirect URL, this is what we use to retrieve the authorization code.

    For users using local server authentication (below) set this to http://localhost:5050 or whatever port you are using.

    Register application

3. Retrieve Client ID

  • Copy client ID and client secret (if the application has a client secret), this will be used to generate an authorization code.

    Copy client id and client secret

4. Authentication

This library has a simplified authentication method based of the MyAnimeList authorization documentation. You can implement your own authentication methods or use the ones provided here.

Four different ways to authenticate with MyAnimeList:

Authenticate using client ID

  • Simply use the client ID for your application. Client secret is not required, even if your application has one.

    MyAnimeList mal = MyAnimeList.withClientID("client_id");

    This authentication method only grants access to public data and READ operations.

    If you want to view users, or change anime/manga lists you must authenticate with a token or with OAuth 2.0

Authenticate using token

  • For developers using their own authorization you can simply use the OAuth token that you generate.

    MyAnimeList mal = MyAnimeList.withToken("Bearer oauth_token");

Authenticate using OAuth 2.0

The below method is massively simplified, for a more detailed explanation on OAuth2.0 works check this forum post: OAuth2.0 authorization for MAL.

For developers using their own authorization methods you can use the MyAnimeListAuthenticator to generate an OAuth token from a client id and PKCE code challenge.

  • The URL to obtain the authorization code can be generated using MyAnimeListAuthenticator.getAuthorizationURL(String,String).

    The client secret will be null if your application does not have one.

    This url is not your code.

  • After you authenticate with the above URL you will be redirected to the page you set in step 2. The URL that you are redirected to contains your authorization code.

    Example: http://localhost:5050?code=AUTHORIZATION_CODE

    Typically this is where you would have a local server to process the request and retrieve the code from the query.

    String authorization_url = MyAnimeListAuthenticator.getAuthorizationURL("client_id", "PKCE_code_challenge");
    
    MyAnimeListAuthenticator authenticator = new MyAnimeListAuthenticator(new Authorization("client_id", "client_secret", "authorization_code", "PKCE_code_challenge"));
    MyAnimeList mal = MyAnimeList.withOAuth2(authenticator);

    It is suggested that you save the OAuth token that is generated so you don't have to authenticate with MyAnimeList each time.

The above methods is massively simplified, for a more detailed guide on how OAuth2.0 works check this blog post: OAuth2.0 authorization for MAL.

Authenticate using a local server

  • For developers without domain for the app redirect url (using localhost), authorization can be completed using the MyAnimeListAuthenticator.

    The app redirect url should be http://localhost:5050 or whatever port you set it as in step 2.

    The client secret will be null if your application does not have one.

  • When this method is run it will launch your web browser to authenticate with MyAnimeList and then return with the OAuth key.

  • If openBrowser() is not supported then you can use setURLCallback(Consumer<String>) to handle the generated URL. Refer to OAuth2.0 authentication for steps on how to generate a token from the authorization URL.

    MyAnimeListAuthenticator authenticator = new MyAnimeListAuthenticator
        .LocalServerBuilder("client_id", "client_secret", 5050)
        .openBrowser()
        .build();
    MyAnimeList mal = MyAnimeList.withOAuth2(authenticator);