Newzbin API:Bookmarks
From Newzbin Documentation
Contents |
[edit] What is it?
The bookmarks API grants authenticated access to a user's report bookmarks for external manipulation.
The user must be a Premium Member to use this API.
[edit] Technical Specifications
This API is implemented on Newzbin v3 (http://v3.newzbin.com or http://www.newzbin.com) only - it is not available on the old "v2" site, at http://v2.newzbin.com.
You access it by sending a standard application/x-www-form-urlencoded POST request to http://www.newzbin.com/api/bookmarks/
[edit] Mandatory Variables
You must supply the following querystring parameters:
- username - The username of the account to login with.
- password - The password of the account to login with.
- action - What to do. see below.
username and password are hopefully self-explanatory.
[edit] action
This field describes what you want the API to do. The following arguments are permitted:
- fetch - Just return a list of IDs from bookmarks, possibly filtered/sorted/limited by the optional variables below.
- delete - Remove the supplied IDs (see below) from the list of bookmarks. There is no confirmation. Handle the confirmation in your application.
When asking the API to delete IDs, you must also supply the reportids parameter, which can contain one or more ReportIDs to delete. Separate more than one with commas.
[edit] Optional Variables
These variables are not required (unless noted), but will define the behaviour of certain actions when supplied. If supplied for an action for which they will have no effect, they are silently ignored.
- Fetch Mode
- sortby - Sort the list of IDs returned by fetch (defaulting to bookmarked_time)
- limit - Only return this many IDs. There is no offset parameter. The top of the list will always be returned. This parameter is only intended as a sanity limit to prevent you receiving possibly hundreds of bookmarks.
- Delete Mode
- reportids - (required) Delete these IDs. Comma-separate multiple IDs.
[edit] sortby
Sort the returned list by the given column. The available sort columns are:
- creation_time (the time the Report was created - oldest first)
- bookmarked_time (the time the Report was bookmarked - oldest first)
- size (the total size of the Report - largest first)
If this parameter is not supplied, bookmarked_time is assumed.
[edit] List of Return Codes
The HTTP response code is used to communicate errors (or success) to you. It will be set to one of the following (the text in parentheses is the reason why it was set, and will not actually be in the response).
- 200 = OK
- 204 = No Content (there were no results to return)
- 400 = Bad Request (you sent an action parameter we didn't understand)
- 402 = Payment Required (the account is not a premium account)
- 403 = Forbidden (incorrect authentication details)
- 500 = Internal Server Error (Newzbin broke)
- 503 = Service Unavailable, site is currently down
[edit] Successful Response
[edit] Fetching
The only successful response is a HTTP response of 200. A 204 indicates the request is valid, but no Bookmarks are being returned.
Upon receiving code 200, you should read the body for results. It's formatted much like an XOVER from a news server.
The fields are TAB separated, and they are:
- ReportID; numerical ID you can use further to pass to DirectNZB etc
- Size; size of the report in bytes, with no comma separators
- Title; title of the report
For example:
2850300 5045249669 Sorcerer (1977) 3003603 5088997637 Brassed Off (1996)
[edit] Deleting
If you receive a 200 response code to a delete, then you should check the body for a single integer, which describes how many reports have been deleted.
This can be anything from 0 (no reports deleted - trying to delete an ID that wasn't bookmarked etc) upwards.
[edit] Technical Limitations
This section describes shortcomings in the current incarnation of the interface; ie things we'd like to fix in the future but we're not sure how to do it yet.
- There is an internal hard limit of 10,000 Bookmarked items - if a user has more than this, some of them will be blatantly ignored. Some behavior is undefined if a user has more than 10,000 reports.
[edit] Updates to Service/this Document
[newest entries at the top]
- 20080418 Service goes live