E621-api NPM | npm.io

e621-api

About

This is an API wrapper for the site e621 to assist in any projects you might have that need API use.

A project to better document the general API can be found here

If you're here, you know what this site is for.

PLEASE NOTE:

This is still in BETA development, if something doesn't work or isn't defined correctly, please let me know!

Getting Started

This project is available via NPM:

npm install e621-api --save

You should have Node 8.9.4 and tsc 2.1 or higher to be safely running this.

Note: When calling the wrapper class you must provide a user-agent or e621 will deny your API requests.

For typeScript setup is easy:

import e621 from 'e621-api'
import { e621PostData } from 'e621-api/build/interfaces';
import { e621TagTypes, e621PopularityStrings } from 'e621-api/build/enums';
 
// First argument is your user-agent, the second is your optional user_name login. The third is your optional passwrod and the last is the page limit per search result (pageLimit * 50 = maximum number of results returned)
let wrapper = new e621('Node-test-1.0', null, null, 3);
 
wrapper.posts.getPopularPosts(e621PopularityStrings.daily)
.then((data) => {
    console.log(data[0].file_url);
})

ES6 requires slightly different setup

let e621 = require('e621-api').default;
let enums = require('e621-api/build/enums');
let wrapper = new e621('Node-test-1.0', null, null, 3);
 
// First argument is your user-agent, the second is your optional user_name login. The third is your optional passwrod and the last is the page limit per search result (pageLimit * 50 = maximum number of results returned)
wrapper.posts.getPopularPosts(enums.e621PopularityStrings.daily)
.then((data) => {
    console.log(data[0].file_url);
})

Available Method Endpoints

If you want more information for any method, check the docs/ folder. Not all methods per endpoint are listed here.

Any time a GET request is made (you receiving data), if invalid parameters are given they will typically be ignored by the API.

Note: the wrapper const used here is representative of your instanced e621 class, for simplicity

Posts

Posts have a lot of endpoints, some common endpoints are below. Posts are the main data type of e621, these can be pictures, videos or flash animations

generatePostUrl

Generate a post's URL by ID, parameters are postID

let postURL = wrapper.posts.generatePostUrl(12345);
console.log(postURL);

getIndexPaginate

Get the post index of e621, using pagination to iterate over a set of pages. Useful for getting a lot of images. Parameters are tags?, start?, limitPerPage?, pageLimit?. Providing no arguments paginates over e621's index (most recent).

wrapper.posts.getIndexPaginate('fox bear order:favcount', 1, 35, 3)
    .then((results) => {
        console.log(results[0][0].file_url);
    })

getPopularPosts

Get a set of the popular posts using the e621PopularityStrings enum, parameter is typeArg

wrapper.posts.getPopularPosts(e621PopularityStrings.daily)
    .then((results) => {
        console.log(results[0].artist);
    })

Pools

Pools contain sets of posts related to a specific topic or series. Note that locking pools through the wrapper is supported, as it required moderator+ access. These are just common examples.

addPost

Add a post to a pool by both the poolID and postID

wrapper.pools.addPost(12345, 56789)
    .then((response) => {
        console.log(response.success);
    })

create

Create a pool to insert a set of posts into, parameters are poolName and poolDescription

wrapper.pools.create('A new Pool Pt. 2', 'Some very descriptive description')
    .then((response) => {
        console.log(response);
    })

destroy

Delete a pool by its ID, parameters are poolID

wrapper.pools.destroy(12463)
    .then((response) => {
        console.log(response);
    })

listPoolPosts

List the posts contained in a pool, parameters are poolID and page?. page is typically not needed if the pool's number of posts is under 25. you can get the count from the API using the response.post_count property from the returned JSON

wrapper.pools.listPoolPosts(12463)
    .then((response) => {
        console.log(response.post_count);
    })

removePost

Remove a post to a pool by both the poolID and postID

wrapper.pools.removePost(12345, 56789)
    .then((response) => {
        console.log(response.success);
    })

updatePoolDescription

Update a pool's description, parameters are poolID and poolDescription

wrapper.pools.updatePoolDescription(123456, 'Some very descriptive update')
    .then((response) => {
        console.log(response);
    })

Artists

To get a list of supported artists methods, check out Artists in the docs/ folder.

Blips

To get a list of supported blips methods, check out Blips in the docs/ folder.

Comments

To get a list of supported comments methods, check out Comments in the docs/ folder.

Dmail

To get a list of supported dmail methods, check out Dmail in the docs/ folder.

Notes

To get a list of supported notes methods, check out Notes in the docs/ folder.

Sets

To get a list of supported set methods, check out Sets in the docs/ folder.

Users

To get a list of supported users methods, check out Users in the docs/ folder.

Wiki

To get a list of supported wiki methods, check out Wiki in the docs/ folder.

Logging in through the API

Some API actions require you to log in.

Logging in through the wrapper is required at the new keyword creation:

// arguments are your user-agent, your login name and your API key (not the same as your password)
let wrapper = new e621('my-user-agent', 'my-user-name', 'my-api-key');

Getting your API key

You can obtain your API key through your user settings on e621 or by using this url:

e621.net/user/login.json?name=USERNAME_HERE&password=PASSWORD_HERE

Interacting directly with the request layer

You can use the requestServices part of the API wrapper to access any endpoints that are not yet available through the wrapper:

wrapper.requestservices.get(`https://e621.net/comment/index.json?post_id=8595`)
    .then((results) => {
        console.log(results)
    })

Any POST calls you make to the API through requestServices will use your login information if it was passed to the class

History

v0.3.9
- Fixed the project not working on *nix Operating Systems

v0.3.8
- Minor doc updates
- Internal pagination system now returns <any>

v0.3.7
- Added support for Set endpoints
- Automatically converting set endpoints into JSON as the XML endpoints are 30x faster but are harder to parse
- Improved the XML conversion engine + per-class support for special cases
- Removed debug GET/POST logging

v0.3.6
- Added support for Wiki endpoints (what actually works, anyway)

v0.3.5
- Added support for Notes
- Added getFavorites method to Posts
- Moving closer to completing the API wrapping

v0.3.4
- Added support for Dmail
- Modified the RequestServices get method to support API-key form submission (required for personal info GET requests)

v0.3.3
- Added support for Blips

v0.3.2
- Fixed a really bad typings issue (Thanks node)

v0.3.1
- Added support for all Pools endpoints
- Improved interface definitions for the wrapper (less any: keyword)

v0.3.0
- Artist, Tags, and Posts are mostly available for use. Posts do not yet support Create/Update/Deletes
- Major changes, improved code structure and readability
- Created a way to GET and POST to the API when a certain endpoint is not supported
- Updated the docs and methods to be clearer