• View
• Edit
• History
• Attach
• Print
• Backlinks

PmPinboardAPI

Questions answered by this recipe

How do I write a recipe that interacts with the social bookmarking site Pinboard?

Description

Pm Pinboard API is a PmWiki Pinboard API library. It provides an easy way for recipe developers to interact with the Pinboard API.

Git repository for this recipe: https://git.sr.ht/~achmizs/pmwiki-pinboard-api.git.

NOTE: This recipe is for recipe developers only. It does not actually do anything by itself; it can be used to write other recipes that deal with Pinboard in some way.

See the Pinboard API documentation for information on how the Pinboard API works.

Quick start guide

1. Download pm-pinboard-api.phpΔ and place it in your cookbook/ folder
2. In a recipe in which you want to use Pm Pinboard API, do the following:
   1. Set your Pinboard API token:
      $PinboardAPIToken = YOUR_API_TOKEN_GOES_HERE;
   2. Include the Pm Pinboard API library:
      include_once("$FarmD/cookbook/pm-pinboard-api.php");
   3. Make Pinboard API requests by calling the PinboardAPIRequest($method, $params) function
      $method is one of the allowed API methods, $params is an array of arguments; the return value is an array containing the response to the API call

For detailed instructions/info, see below.

Installation

Download pm-pinboard-api.phpΔ and place it in your cookbook/ folder. Then place this line in any recipe where you want to use Pm Pinboard API:

 include_once("$FarmD/cookbook/pm-pinboard-api.php");

Configuration

Pm Pinboard API uses the following variables. (If you’re modifying any of these, do so before including pm-pinboard-api.php.)

$PinboardAPIEndpoint (default: https://api.pinboard.in/v1/)

The root URL of the Pinboard API endpoint. You should not need to change this value (of course, it will need to be modified if the Pinboard API endpoint URL ever changes).

$PinboardAPIToken

The Pinbord API token for a registered Pinboard user (in the form of username:alphanumeric_string). (If you’re logged into Pinboard, you can find your API token by going to https://pinboard.in/settings/password.) The API token must be set in order for Pm Pinboard API to work! All Pinboard API functions require authentication!

$PinboardAPIAllowedMethods

An array of Pinboard API methods that are available. The default setting is:

array(
	'posts/update',
// 	'posts/add',
// 	'posts/delete',
	'posts/get',
	'posts/recent',
	'posts/dates',
	'posts/all',
	'posts/suggest',

	'tags/get',
// 	'tags/delete',
// 	'tags/rename',

	'user/secret',

	'notes/list',
	'notes/ID'
);

Note that all of the methods that modify the user’s data in any way are disabled by default. (This includes posts/add, posts/delete, tags/delete, and tags/rename.)

$PinboardAPIMethodCooldowns

An array that specifies the “minimum cooldowns” of various Pinboard API calls (i.e., the minimum time that must elapse between two requests of that type).You should not need to change this value. (If the values in this array don’t conform to the Pinboard API specification, bad things may result!)

$PinboardAPICacheFolder (default: pub/cache/pinboard/)

The folder where Pm Pinboard API saves the request log. The path must be writeable by the webserver.

$PinboardAPIResponseCacheDuration (default: 0)

Length of time for which to cache responses to API requests, in seconds. 0 (or negative values) disables response caching. If response caching is enabled, then Pm Pinboard API will not send a request if it has a cached response to the same request that is younger than the specified duration, and will instead return the cached response. (Note that any positive value for this variable will be rounded up to the maximum value in $PinboardAPIMethodCooldowns (which should be 300, i.e. 5 minutes). In other words, $PinboardAPIResponseCacheDuration can be 0 (caching disabled), or it can be 300 or higher; intermediate values are not allowed.)

Usage

Pm Pinboard API provides the following functions, for interacting with the Pinboard API.

(NOTE: See the Pinboard API documentation for details on what parameters each method takes, and what responses are possible. Remember that a valid API key must be provided for any of this to work!)

Other functions

The other functions provided by Pm Pinboard API have to do with the request log and the response cache. In normal use, you should not need to call these functions. Their purpose and functionality is described below for completeness only.

The request log

Pm Pinboard API keeps a log file called request_log.json (in the folder specified by $PinboardAPICacheFolder). This log file contains four values:

last-global

The time (as a Unix timestamp) of the last Pinboard API request of any kind (or 0 if no API request has ever been made / if the log has been reset).

last-posts/recent

The time (as a Unix timestamp) of the last Pinboard API request with the posts/recent method (or 0 if no API request with this method has ever been made / if the log has been reset).

last-posts/all

The time (as a Unix timestamp) of the last Pinboard API request with the posts/all method (or 0 if no API request with this method has ever been made / if the log has been reset).

last_request_hash

An MD5 hash of the request URL of the last Pinboard API request (of any kind). (Empty if no API request has ever been made / if the log has been reset). The request URL hash is used as an index into the response cache file (see “The response cache”, below).

The following functions deal with the request log:

PinboardAPIResetRequestLog()

Resets the request log to its initial state (creating the request_log.json file if it does not already exist).

PinboardAPIGetRequestLog()

Returns the request log (as an array, containing the keys/values listed above), having read it from the file request_log.json (in the folder specified by $PinboardAPICacheFolder).

PinboardAPISaveRequestLog($request_log)

Takes the array passed to it (which should contain the keys/values listed above) and saves it to the file request_log.json (in the folder specified by $PinboardAPICacheFolder).

The response cache

Pm Pinboard API keeps a file called response_cache.json (in the folder specified by $PinboardAPICacheFolder). The keys in this file are MD5 hashes of Pinboard API request URLs; the value for each key is the response to that request.

If response caching is enabled (that is, if $PinboardAPIResponseCacheDuration is set to a positive value), then response_cache.json stores the responses for every request which has been sent since caching was enabled.

If response caching is disabled (that is, if $PinboardAPIResponseCacheDuration is set to a non-positive value), then response_cache.json stores the response to the last request only. (When caching is disabled, then all previous responses are discarded when a new response is stored.)

Responses are arrays. Each response contains values for two special keys, in addition to all the values set by the Pinboard API itself. These are:

request_time

The time (as a Unix timestamp) at which the request was made.

http_code

The HTTP status code associated with the response. If the response was successful, this should be 200. A status code of 429 indicates that too many requests had been sent in a short time. Some other status code usually indicates some sort of problem.

The following functions deal with the response cache:

PinboardAPIClearResponseCache()

Clears the response cache (creating the response_cache.json file if it does not already exist).

PinboardAPIGetResponseCache()

Returns the response cache (as an array, containing the keys/values listed above), having read it from the file response_cache.json (in the folder specified by $PinboardAPICacheFolder).

PinboardAPIUpdateResponseCache($request_URL_hash, $response)

Updates the response cache, saving the provided response for the provided hash value (which should be an MD5 hash of the request URL). (If caching is disabled, any previously saved responses are discarded.) The response cache is saved to the file response_cache.json (in the folder specified by $PinboardAPICacheFolder).

To do / some day / maybe

I may add a feature that automatically cleans the response cache of old responses.

Change log / Release notes

• 2021-12-12: Updated license.
• 2018-01-09: Initial release.

Contributors

• Said Achmiz

Comments

See discussion at PmPinboardAPI-Talk