Skip to content

Latest commit

 

History

History
138 lines (109 loc) · 5.19 KB

readme.md

File metadata and controls

138 lines (109 loc) · 5.19 KB
Raw

drawing

Metron Comics Client

This is a straightforward client written in Kotlin, designed to navigate and query the https://metron.cloud/ API. The API allows users to search for information about comics from the metron database.

Getting Started

To begin, import the library using jitpack.io.

You can include jitpack in your pom.xml by using the following code:

<repository>
    <id>jitpack.io</id>
    <url>https://www.jitpack.io</url>
</repository>

Then add this Metron Comics Client Library to your project!

<dependency>
    <groupId>com.github.official-wizard</groupId>
    <artifactId>metron-comics</artifactId>
    <version>1.0.1</version>
</dependency>

Tips

  • It's recommended to implement a cache system to prevent re-querying!

Credentials

To gain your credentials to access the API you must create an account on https://metron.cloud, the username and password you use is what will be used to access the API!

Usage

To begin, create an instance of the Client/API to access metron!

Create instance

// your Metron credentials
val credentials: Credentials = Credentials("<username>", "<password>")

// client instance 
val client: MetronClient = MetronClient(credentials)

// api access
val api = client.api

Search Issue Example

Search for a list of available issues by the provided query parameters!

Available Parameters (Optional)

These parameters are available to filter for comics available based on the provided information!

Filter Description
series_name filter by series name
cover_month filter by cover month
cover_year filter by cover year
cv_id filter Comic Vine ID
modified_gt filter by last modified greather than date (e.g Sat,22 Jul 2023 04:20:52 GMT)
number filter by issue number
page select a query page to traverse
publisher_id filter by publisher id
publisher_name filter by publisher name
series_id filter by series id
series_year_began filter by year series began
sku filter by barcode (sku)
store_date filter by store date
store_date_range_after filter by store date after
store_date_range_before filter by store date before
upc filter by UPC id

Note

In this example we use 2 endpoints to retrieve information, 1 for obtaining a list of issues available by the provided query, and the other for obtaining details on the selected issue from the list of issues. This is done as it's required to use the ID to fetch details on the issue requested!

Example

// your Metron credentials
val credentials: Credentials = Credentials("<username>", "<password>")

// client instance 
val client: MetronClient = MetronClient(credentials)

// api access
val api = client.api

// search for issues by series name
val issuesRequest = api.getIssues(series_name = "Howard the Duck").execute()
if (!issuesRequest.isSuccessful) {
    // handle error, e.g. issuesRequest.errorBody() 
    return
}

// obtain the request body
val issues = issuesRequest.body()
if (issues == null) {
    // unexpected null body this usually happens if there's an error, 
    // as above
    return
}

// no results were returned
if (issues.results.isEmpty()) {
    // handle no issues being available by the query parameters
    return
}

val firstIssue = issues.results.first()
val firstIssueId = firstIssue.id

// -- 2nd usage for obtaining details on the first issue from the results --

// search for the details for the issue's ID obtained
val issueDetailsRequest = api.getIssue(firstIssueId).execute()
if (!issueDetailsRequest.isSuccessful) {
    // handle error, e.g. issueResponse.errorBody() 
    return
}

// obtain details
val issueDetails = issueDetailsRequest.body()
if (issueDetails == null) {
    // null check and handle unexpected null body
    // this usually happens if there's an error, as above
    return
}

// do as you wish with the issueDetails available!
println(issueDetails.desc)