edshot99/eBooru
1
0
Fork 0
forked from e621ng/e621ng
Code Issues 11 Releases 1 Activity

[Misc] Delete api.txt and add doc folder to gitignore

Browse Source 
The file was last updated 4 years ago and is pretty outdated.
Incorrect documentation is often worse than no documentation.
YARD throws it's files there, and also in .yardoc, ignore those
This commit is contained in:
Earlopain 2021-07-05 13:22:05 +02:00
parent 6910369e2a
commit eb271ca799
No known key found for this signature in database
GPG Key ID: 6CFB948E15246897
2 changed files with 2 additions and 670 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.gitignore vendored
View File

@ -1,11 +1,13 @@
.env.* .env.*
.bundle .bundle
.yardoc
config/database.yml config/database.yml
config/danbooru_local_config.rb config/danbooru_local_config.rb
config/deploy/*.rb config/deploy/*.rb
config/application.yml config/application.yml
config/newrelic.yml config/newrelic.yml
db/*.sqlite3 db/*.sqlite3
doc/*
log/*.log log/*.log
tmp/* tmp/*
public/data public/data

670
doc/api.txt
View File

@ -1,670 +0,0 @@
Danbooru offers a REST-like API to make scripting easy. All you need is a way to GET, POST, PUT and DELETE to URLs. Responses are given in either XML or JSON format.
h1. Basics
HTTP defines four basic request methods: GET, POST, PUT and DELETE. You'll be using these methods to interact with the Danbooru API. Most API calls that change the state of the database (like creating, updating, or deleting something) require an HTTP POST, PUT or DELETE call. API calls that only retrieve data can typically be done with an HTTP GET call.
A URL is considered a resource and the HTTP methods are actions you perform on the resource. For example, GET "/posts/1.json":/posts/1.json returns a JSON representation of a post. GET "/posts/1.xml":/posts/1.xml returns an XML representation. POST /posts/1.json would update the resource, for example changing its tags.
Some resources require parameters. For example, you can find tags that start with the letter a by calling GET "/tags.json?search[name_matches]=a*":/tags.json?search[name_matches]=a*. This will give you a JSON listing of all tags with names starting with an a.
For POST, PUT and DELETE requests you will be passing these parameters along in the body instead of the query parameters.
h1. Responses
All API calls that change state will return a single element response (for XML calls). They are formatted like this:
[quote]
<?xml version="1.0" encoding="UTF-8"?>
<response success="false" reason="duplicate"/>
[/quote]
For JSON responses, they'll look like this:
[quote]
{ "success": false, "reason": "duplicate" }
[/quote]
While you can usually determine success or failure based on the response object, you can also figure out what happened based on the HTTP status code. In addition to the standard ones, Danbooru uses some custom status codes in the 4xx and 5xx range.
* [b]200 OK[/b]: Request was successful
* [b]204 No Content[/b]: Request was successful
* [b]403 Forbidden[/b]: Access denied
* [b]404 Not Found[/b]: Not found
* [b]420 Invalid Record[/b]: Record could not be saved
* [b]421 User Throttled[/b]: User is throttled, try again later
* [b]422 Locked[/b]: The resource is locked and cannot be modified
* [b]423 Already Exists[/b]: Resource already exists
* [b]424 Invalid Parameters[/b]: The given parameters were invalid
* [b]500 Internal Server Error[/b]: Some unknown error occurred on the server
* [b]503 Service Unavailable[/b]: Server cannot currently handle the request, try again later
h1. Authentication
If you can't maintain a session via a cookie, you can pass in two parameters to authenticate: login and api_key. For legacy users, password_hash using the old salted SHA1 hashed password is also supported. Your API key is equivalent to your bcrypted password hash, which is stored in your cookies as password_hash. You can discover your API key by visiting your user profile. Your API key is intended to be a secret so you should not publicly distribute it.
You can also authenticate via HTTP Basic Authentication using your user name and API key.
If you are writing a user script for a browser, you do not need to embed an API key. You can rely on the user's session.
Anonymous users can make 500 requests an hour. Basic members can make 3,000 requests an hour. Gold members can make 10,000 requests an hour. Platinum members can make 20,000 requests an hour.
h1. Queries
[expand=Posts]
h2. Listing
The base URL is GET /posts.json.
* [b]limit[/b] How many posts you want to retrieve. There is a hard limit of 100 posts per request.
* [b]page[/b] The page number.
* [b]tags[/b] The tags to search for. Any tag combination that works on the web site will work here. This includes all the meta-tags.
* [b]raw[/b] When this parameter is set the tags parameter will not be parsed for aliased tags, metatags or multiple tags, and will instead be parsed as a single literal tag.
h2. Show
The base URL is GET /posts/$id.json where $id is the post id.
h2. Create
You cannot directly create posts. You must create an upload, which is then converted into a post.
h2. Update
The base URL is PUT /posts/$id.json where $id is the post id.
* [b]post[tag_string][/b] A space delimited list of tags.
* [b]post[rating][/b] The rating for the post. Can be: s (for safe), q (for questionable), or e (for explicit).
* [b]post[source][/b] If this is a URL, Danbooru will download the file.
* [b]post[parent_id][/b] The ID of the parent post.
h2. Delete
You cannot delete posts. You can only flag them for deletion (see PostFlag resource).
h2. Revert
The base URL is PUT /posts/$id/revert.json where $id is the post id.
* [b]version_id[/b] REQUIRED The post version id to revert to.
h2. Copy notes
The base URL is PUT /posts/$id/copy_notes.json where $id is the post id.
* [b]other_post_id[/b] REQUIRED The id of the post to copy notes to.
[/expand]
[expand=Post Votes]
h2. Create
The base URL is POST /posts/$post_id/votes.json where $post_id is the post id.
* [b]score[/b] REQUIRED Can be: up, down.
[/expand]
[expand=Post Flags]
h2. Listing
The base URL is GET /post_flags.json.
* [b]search[creator_id][/b] The user id of the flag's creator.
* [b]search[creator_name][/b] The name of the flag's creator.
* [b]search[post_id][/b] The post id if the flag.
h2. Create
The base URL is POST /post_flags.json.
* [b]post_flag[post_id][/b] REQUIRED The id of the flagged post.
* [b]post_flag[reason][/b] REQUIRED The reason of the flagging.
[/expand]
[expand=Post Appeals]
h2. Listing
The base URL is GET /post_appeals.json.
* [b]search[creator_id][/b] The user id of the appeal's creator.
* [b]search[creator_name][/b] The name of the appeal's creator.
* [b]search[post_id][/b] The post id if the appeal.
h2. Create
The base URL is POST /post_appeals.json.
* [b]post_appeal[post_id][/b] REQUIRED The id of the appealed post.
* [b]post_appeal[reason][/b] REQUIRED The reason of the appeal.
[/expand]
[expand=Uploads]
h2. Listing
The base URL is GET /uploads.json.
* [b]search[uploader_id][/b] The id of the uploader.
* [b]search[uploader_name][/b] The name of the uploader.
* [b]search[source][/b] The source of the upload (exact string match).
h2. Show
The base URL is GET /uploads/$id.json where $id is the upload id.
h2. Create
The base URL is POST /uploads.json.
* [b]upload[file][/b] The file data encoded as a multipart form.
* [b]upload[source][/b] The source URL.
* [b]upload[rating][/b] REQUIRED Can be: safe, questionable, explicit.
* [b]upload[parent_id][/b] The parent post id.
* [b]upload[tag_string][/b] REQUIRED The tags.
Either the file or the source must be provided.
[/expand]
[expand=Comments]
h2. Listing
The base URL is GET /comments.json.
* [b]group_by[/b] Must be: comment
* [b]search[body_matches][/b] Body contains the given terms.
* [b]search[post_id][/b]
* [b]search[post_tags_match][/b] The comment's post's tags match the given terms. Meta-tags not supported.
* [b]search[creator_name][/b] The name of the creator (exact match)
* [b]search[creator_id][/b] The user id of the creator
h2. Create
The base URL is POST /comments.json
* [b]comment[post_id][/b] REQUIRED
* [b]comment[body][/b] REQUIRED
* [b]comment[do_not_bump_post][/b] Set to 1 if you do not want the post to be bumped to the top of the comment listing
h2. Update
The base URL is PUT /comments/$id.json where $id is the comment id.
* [b]comment[body][/b] REQUIRED
* [b]comment[do_not_bump_post][/b] Set to 1 if you do not want the post to be bumped to the top of the comment listing
h2. Show
The base URL is GET /comments/$id.json where $id is the comment id.
h2. Delete
The base URL is DELETE /comments/$id.json where $id is the comment id.
[/expand]
[expand=Dmails]
h2. Listing
The base URL is GET /dmails.json. You can only view dmails you own.
* [b]search[message_matches][/b] The message body contains the given terms.
* [b]search[to_name][/b] The recipient's name.
* [b]search[to_id][/b] The recipient's user id.
* [b]search[from_name][/b] The sender's name.
* [b]search[from_id][/b] The sender's user id.
* [b]search[read][/b] Can be: true, false
h2. Show
The base URL is GET /dmails/$id.json where $id is the dmail id. You can only view dmails you own.
h2. Create
The base URL is POST /dmails.json.
* [b]dmail[to_name][/b] The recipient's name.
* [b]dmail[title][/b] The title of the message.
* [b]dmail[body][/b] The body of the message.
h2. Delete
The base URL is DELETE /dmails/$id.json where $id is the dmail id. You can only delete dmails you own.
[/expand]
[expand=Artists]
h2. Listing
The base URL is GET /artists.json.
* [b]search[name][/b] This field has multiple uses depending on what the query starts with:
** [i]http[/i] Search for artist with this URL.
** [i]name:[/i] Search for artists with the given name as their base name..
** [i]other:[/i] Search for artists with the given name in their other names.
** [i]group:[/i] Search for artists belonging to the group with the given name.
** [i]status:banned[/i] Search for artists that are banned.
** [i]else[/i] Search for the given name in the base name and the other names.
* [b]search[id][/b] The artist id.
* [b]search[creator_name][/b]
* [b]search[creator_id][/b]
* [b]search[is_active][/b] Can be: true, false
* [b]search[is_banned][/b] Can be: true, false
* [b]search[empty_only][/b] Search for artists that have 0 posts. Can be: true
* [b]search[order][/b] Can be: name, date.
h2. Show
The base URL is GET /artists/$id.json where $id is the artist id.
h2. Create
The base URL is POST /artists.json.
* [b]artist[name][/b]
* [b]artist[other_names_comma][/b] List of alternative names for this artist, comma delimited.
* [b]artist[group_name][/b] The name of the group this artist belongs to.
* [b]artist[url_string][/b] List of URLs associated with this artist, whitespace or newline delimited.
h2. Update
The base URL is PUT /artists/$id.json where $id is the artist id.
* [b]artist[name][/b]
* [b]artist[other_names_comma][/b] List of alternative names for this artist, comma delimited.
* [b]artist[group_name][/b] The name of the group this artist belongs to.
* [b]artist[url_string][/b] List of URLs associated with this artist, whitespace or newline delimited.
h2. Delete
The base URL is DELETE /artists/$id.json where $id is the artist id.
h2. Banned
The base URL is GET /artists/banned.json. This is a shortcut for an artist listing search with name=status:banned.
h2. Revert
The base URL is PUT /artists/$id/revert.json where $id is the artist id.
* [b]version_id[/b] REQUIRED The artist version id to revert to.
[/expand]
[expand=Notes]
h2. Listing
The base URL is GET /notes.json.
* [b]search[body_matches][/b] The note's body matches the given terms.
* [b]search[post_id][/b]
* [b]search[post_tags_match][/b] The note's post's tags match the given terms. Meta-tags are not supported.
* [b]search[creator_name][/b] The creator's name. Exact match.
* [b]search[creator_id][/b] The creator's user id.
Use /notes.json?group_by=note&search[post_id]=$id to get notes from $id.
h2. Show
The base URL is GET /notes/$id.json where $id is the note id.
h2. Create
* [b]note[post_id][/b] REQUIRED
* [b]note[x][/b] REQUIRED The x coordinates of the note in pixels, with respect to the top-left corner of the image.
* [b]note[y][/b] REQUIRED The y coordinates of the note in pixels, with respect to the top-left corner of the image.
* [b]note[width][/b] REQUIRED The width of the note in pixels.
* [b]note[height][/b] REQUIRED The height of the note in pixels.
* [b]note[body][/b] REQUIRED The body of the note.
h2. Update
The base URL is PUT /notes/$id.json where $id is the note id.
* [b]note[x][/b] The x coordinates of the note in pixels, with respect to the top-left corner of the image.
* [b]note[y][/b] The y coordinates of the note in pixels, with respect to the top-left corner of the image.
* [b]note[width][/b] The width of the note in pixels.
* [b]note[height][/b] The height of the note in pixels.
* [b]note[body][/b] The body of the note.
h2. Delete
The base URL is DELETE /notes/$id.json where $id is the note id.
h2. Revert
The base URL is PUT /notes/$id/revert.json where $id is the note id.
* [b]version_id[/b] REQUIRED The note version id to revert to.
[/expand]
[expand=Users]
h2. Levels
Users have a number attribute called level representing their role. The current levels are:
* Member: 20
* Gold: 30
* Platinum: 31
* Builder: 32
* Moderator: 40
* Admin: 50
h2. Listing
The base URL is GET /users.json.
* [b]search[name][/b] Supports patterns.
* [b]search[min_level][/b] Minimum level (see section on levels).
* [b]search[max_level][/b] Maximum level (see section on levels).
* [b]search[level][/b] Current level (see section on levels).
* [b]search[id][/b] The user id.
* [b]search[order][/b] Can be: name, post_upload_count, note_count, post_update_count, date.
h2. Show
The base URL is GET /users/$id.json where $id is the user id.
[/expand]
[expand=Post Versions]
h2. Listing
The base URL is GET /post_versions.json.
* [b]search[updater_name][/b]
* [b]search[updater_id][/b]
* [b]search[post_id][/b]
* [b]search[start_id][/b]
[/expand]
[expand=Note Versions]
h2. Listing
The base URL is GET /note_versions.json.
* [b]search[updater_id][/b]
* [b]search[post_id][/b]
* [b]search[note_id][/b]
[/expand]
[expand=Artist Versions]
h2. Listing
The base URL is GET /artist_versions.json.
* [b]search[name][/b]
* [b]search[updater_id][/b]
* [b]search[artist_id][/b]
* [b]search[is_active][/b] Can be: true, false
* [b]search[is_banned][/b] Can be: true, false
* [b]search[order][/b] Can be: name, date
[/expand]
[expand=Pools]
h2. Listing
The base URL is GET /pools.json.
* [b]search[name_matches][/b]
* [b]search[description_matches][/b]
* [b]search[creator_name][/b]
* [b]search[creator_id][/b]
* [b]search[is_active][/b] Can be: true, false
* [b]search[order][/b] Can be: name, created_at, post_count, date
* [b]search[category][/b] Can be: series, collection
h2. Show
The base URL is GET /pools/$id.json where $id is the pool id.
h2. Create
The base URL is POST /pools.json.
* [b]pool[name][/b] REQUIRED
* [b]pool[description][/b] REQUIRED
* [b]pool[category][/b] Can be: series, collection
h2. Update
The base URL is PUT /pools/$id.json where $id is the pool id.
* [b]pool[name][/b]
* [b]pool[description][/b]
* [b]pool[post_ids][/b] List of space delimited post ids.
* [b]pool[is_active][/b] Can be: 1, 0
* [b]pool[category][/b] Can be: series, collection
h2. Delete
The base URL is DELETE /pools/$id.json where $id is the pool id.
h2. Undelete
The base URL is POST /pools/$id/undelete.json where $id is the pool id.
h2. Revert
The base URL is PUT /pools/$id/revert.json where $id is the pool id.
* [b]version_id[/b] REQUIRED
[/expand]
[expand=Pool Versions]
h2. Listing
The base URL is GET /pool_versions.json.
* [b]search[updater_id][/b]
* [b]search[updater_name][/b]
* [b]search[pool_id][/b]
[/expand]
[expand=Tags]
h2. Listing
The base URL is GET /tags.json.
* [b]search[name_matches][/b]
* [b]search[category][/b] Can be: 0, 1, 3, 4 (general, artist, copyright, character respectively)
* [b]search[hide_empty][/b] Can be: yes, no. Excludes tags with 0 posts when "yes".
* [b]search[order][/b] Can be: name, date, count
* [b]search[has_wiki][/b] Can be: yes, no
* [b]search[name][/b] Allows searching for multiple tags with exact given names, separated by commas. e.g. search[name]=touhou,original,k-on! would return the three listed tags.
[/expand]
[expand=Tag Aliases]
h2. Listing
The base URL is GET /tag_aliases.json.
* [b]search[name_matches][/b] Match antecedent or consequent name.
* [b]search[antecedent_name][/b] Match antecedent name (exact match).
* [b]search[id][/b] The tag alias id.
[/expand]
[expand=Tag Implications]
h2. Listing
The base URL is GET /tag_implications.json.
* [b]search[name_matches][/b] Match antecedent or consequent name.
* [b]search[antecedent_name][/b] Match antecedent name (exact match).
* [b]search[id][/b] The tag implication id.
[/expand]
[expand=Wiki Pages]
h2. Listing
The base URL is GET /wiki_pages.json.
* [b]search[title][/b]
* [b]search[creator_id][/b]
* [b]search[body_matches][/b]
* [b]search[other_names_match][/b]
* [b]search[creator_name][/b]
* [b]search[order][/b] Can be: date, title.
h2. Show
The base URL is GET /wiki_pages/$id.json where $id is the wiki page id.
h2. Create
The base URL is POST /wiki_pages.json.
* [b]wiki_page[title][/b] REQUIRED
* [b]wiki_page[body][/b] REQUIRED
* [b]wiki_page[other_names][/b]
h2. Update
The base URL is PUT /wiki_pages/$id.json where $id is the wiki page id.
* [b]wiki_page[title][/b]
* [b]wiki_page[body][/b]
* [b]wiki_page[other_names][/b]
h2. Revert
The base URL is PUT /wiki_pages/$id/revert.json where $id is the wiki page id.
* [b]version_id[/b] REQUIRED
[/expand]
[expand=Related Tags]
h2. Show
The base URL is GET /related_tag.json.
* [b]query[/b] REQUIRED The tag to find the related tags for.
* [b]category[/b] If specified, show only tags of a specific category. Can be:
** [i]General[/i] 0
** [i]Artist[/i] 1
** [i]Copyright[/i] 3
** [i]Character[/i] 4
[/expand]
[expand=Forum Topics]
h2. Listing
The base URL is GET /forum_topics.json.
* [b]search[title_matches][/b] Search body for the given terms.
* [b]search[title][/b] Exact title match.
* [b]search[category_id][/b] Can be: 0, 1, 2 (General, Tags, Bugs & Features respectively)
h2. Show
The base URL is GET /forum_topics/$id.json where $id is the forum topic id.
h2. Create
The base URL is POST /forum_topics.json.
* [b]forum_topic[title][/b]
* [b]forum_topic[original_post_attributes][body][/b] Message of the initial post.
* [b]forum_topic[category_id][/b]
h2. Update
The base URL is PUT /forum_topics/$id.json where $id is the forum topic id.
* [b]forum_topic[title][/b]
* [b]forum_topic[category_id][/b]
h2. Delete
The base URL is DELETE /forum_topics/$id.json where $id is the forum topic id.
h2. Undelete
The base URL is POST /forum_topics/$id/undelete.json where $id is the forum topic id.
[/expand]
[expand=Forum Posts]
h2. Listing
The base URL is GET /forum_posts.json.
* [b]search[creator_id][/b]
* [b]search[creator_name][/b]
* [b]search[topic_id][/b]
* [b]search[topic_title_matches][/b]
* [b]search[topic_category_id][/b] Can be: 0, 1, 2 (General, Tags, Bugs & Features respectively)
* [b]search[body_matches][/b]
h2. Create
The base URL is POST /forum_posts.json.
* [b]forum_post[body][/b]
h2. Update
The base URL is PUT /forum_posts/$id.json where $id is the forum post id.
* [b]forum_post[body][/b]
h2. Delete
The base URL is DELETE /forum_posts/$id.json where $id is the forum post id.
h2. Undelete
The base URL is POST /forum_posts/$id/undelete.json where $id is the forum post id.
[/expand]
[expand=Artist Commentary]
h2. Listing
The base URL is GET /artist_commentaries.json.
* [b]search[text_matches][/b]
* [b]search[post_tags_match][/b] The commentary's post's tags match the given terms. Meta-tags not supported.
* [b]search[original_present][/b] Can be: yes, no
* [b]search[translated_present][/b] Can be: yes, no
h2. Create or Update
The base URL is POST /artist_commentaries/create_or_update.json
* [b]artist_commentary[post_id][/b] REQUIRED
* [b]artist_commentary[original_title][/b]
* [b]artist_commentary[original_description][/b]
* [b]artist_commentary[translated_title][/b]
* [b]artist_commentary[translated_description][/b]
h2. Revert
The base URL is PUT /artist_commentaries/$id/revert.json where $id is the post id (not the artist commentary id).
* [b]version_id[/b] REQUIRED The artist commentary version id to revert to.
[/expand]
[expand=Artist Commentary Versions]
h2. Listing
The base URL is GET /artist_commentary_versions.json.
* [b]search[updater_id][/b]
* [b]search[post_id][/b]
[/expand]