Resource URIs

pin is a command line, but the pinterest Go package is also a small driver that makes Pinterest addressable as a resource URI. A host program registers it the way a program registers a database driver with database/sql, then dereferences pinterest:// URIs without knowing anything about how Pinterest is fetched.

The host that does this today is ant, a single binary that puts one URI namespace over a family of site tools. The examples below use ant; any program that links the package gets the same behaviour.

Mounting the driver

A host enables the driver with one blank import, exactly like import _ "github.com/lib/pq":

import _ "github.com/tamnd/pinterest-cli/pinterest"

The package's init registers a domain with the scheme pinterest for the host pinterest.com. The standalone pin binary does not change.

Addressing records

A URI is scheme://authority/id. The pinterest driver exposes these authorities:

URI	What it is
pinterest://pin/<id>	one pin, keyed by its id
pinterest://board/<user>/<slug>	one board, keyed by its owner and slug
pinterest://user/<name>	one profile, keyed by its username
pinterest://topic/<slug>	one interest topic, keyed by its slug

ant get pinterest://pin/<id>                 # the pin record
ant get pinterest://board/<user>/<slug>      # the board record
ant get pinterest://user/<name>              # the profile record
ant url pinterest://pin/<id>                 # the live https URL
ant resolve https://www.pinterest.com/pin/123456/  # a pasted link, back to its URI

The same classification runs offline through the binary: pin ref id <ref> turns any reference into its (kind, id), and pin ref url <kind> <id> builds the canonical URL.

Walking the graph

ls lists the members of a collection, and every member is itself an addressable URI, so a host can follow the graph and write it to disk:

ant ls     pinterest://board/<user>/<slug>          # the pins on this board
ant export pinterest://user/<name> --follow 1 --to ./data

The board and user list ops emit pin and board stubs, so each listed member is a pinterest:// URI in its own right. When records carry edges through kit:"link" tags, ant export --follow and ant graph walk those edges too, across tools when a link points at another site's scheme.

The empty-feed caveat

Listing the pins on a board or the saves on a profile goes through Pinterest's pin-grid feeds, which can return empty from a datacenter or cloud IP. The metadata authorities (pinterest://board/..., pinterest://user/...) resolve from any network. See troubleshooting.

Why this is the same code

The driver and the binary share one definition per operation. A resolver op answers both pin board show on the command line and ant get pinterest://board/... through a host, from the same handler and the same client. There is no second implementation to keep in step.