Simon Willison’s Weblog

Macaroons Escalated Quickly (via) Thomas Ptacek’s follow-up on Macaroon tokens, based on a two year project to implement them at Fly.io. The way they let end users calculate new signed tokens with additional limitations applied to them (“caveats” in Macaroon terminology) is fascinating, and allows for some very creative solutions. # 31st January 2024, 4:57 pm

Getting started with the Datasette Cloud API. I wrote an introduction to the Datasette Cloud API for the company blog, with a tutorial showing how to use Python and GitHub Actions to import data from the Federal Register into a table in Datasette Cloud, then configure full-text search against it. # 28th September 2023, 11:05 pm

babelmark3 (via) I found this tool today while investigating an bug in Datasette’s datasette-render-markdown plugin: it lets you run a fragment of Markdown through dozens of different Markdown libraries across multiple different languages and compare the results. Under the hood it works with a registry of API URL endpoints for different implementations, most of which are encrypted in the configuration file on GitHub because they are only intended to be used by this comparison tool. # 27th January 2023, 11:34 pm

API Tokens: A Tedious Survey. Thomas Ptacek reviews different approaches to implementing secure API tokens, from simple random strings stored in a database through various categories of signed token to exotic formats like Macaroons and Biscuits, both new to me.

Macaroons carry a signed list of restrictions with them, but combine it with a mechanism where a client can add their own additional restrictions, sign the combination and pass the token on to someone else.

Biscuits are similar, but “embed Datalog programs to evaluate whether a token allows an operation”. # 25th August 2021, 12:12 am

Custom Properties as State. Fascinating thought experiment by Chris Coyier: since CSS custom properties can be defined in an external stylesheet, we can APIs that return stylesheets defining dynamically server-side generated CSS values for things like time-of-day colour schemes or even strings that can be inserted using ::after { content: var(--my-property).

This gave me a very eccentric idea for a Datasette plugin... # 7th January 2021, 7:39 pm

PostGraphile: Production Considerations. PostGraphile is a tool for building a GraphQL API on top of an existing PostgreSQL schema. Their “production considerations” documentation is particularly interesting because it directly addresses some of my biggest worries about GraphQL: the potential for someone to craft an expensive query that ties up server resources. PostGraphile suggests a number of techniques for avoiding this, including a statement timeout, a query allowlist, pagination caps and (in their “pro” version) a cost limit that uses a calculated cost score for the query. # 27th March 2020, 1:22 am

Building a stateless API proxy (via) This is a really clever idea. The GitHub API is infuriatingly coarsely grained with its permissions: you often end up having to create a token with way more permissions than you actually need for your project. Thea Flowers proposes running your own proxy in front of their API that adds more finely grained permissions, based on custom encrypted proxy API tokens that use JWT to encode the original API key along with the permissions you want to grant to that particular token (as a list of regular expressions matching paths on the underlying API). # 30th May 2019, 4:28 am

How we made an API for BoingBoing in an evening. Fluidinfo really is a fascinating piece of software. The team loaded in 11 years of BoingBoing content, allowing you to run structured queries against the data using their standard API, but also allowing users to attach their own information to the same corpus using Fluidinfo tags. Writable APIs are much less common than read-only APIs—Fluidinfo instantly provides both. # 28th January 2011, 10:56 pm

Google APIs & Developer Products. Presented as a sort-of-periodic table. There’s quite a bit of stuff on here I didn’t know about. # 28th January 2011, 11:25 am

Tip: Flickr standard photo response as slideshow. Neat trick—you can construct a URL to Flickr’s slideshow widget that includes the results of any API method, including the all-powerful flickr.photos.search. It’s a shame you can’t embed the resulting slideshow in an iframe. # 25th January 2011, 3:51 am

Introducing the FluidDB Explorer. Every good API deserves a dedicated API browser. # 13th January 2011, 4:19 am

Yahoo! Developer Network: Important API Updates and Changes. Some important (and potentially worrying) news about Yahoo! APIs. The BOSS (Build your Own Search Service) API will no longer be free—not an enormous surprise, and hopefully the pricing will be sensible. Most of the other search APIs (including web, news and image search) are being turned off with no replacement, while term extraction and spelling suggestions will be YQL-only. Most worrying, changes to Geo, Maps and Local APIs will be announced in September, with some set to close. I really hope this doesn’t affect the GeoPlanet APIs. # 17th August 2010, 6:14 pm

Writing Bulletproof Apps with API Errorpoints. This is a very good idea: Web APIs should offer special API endpoints for simulating each of the possible errors that might be returned by the production API. # 16th August 2010, 7:12 pm

Closure Compiler Service (via) A hosted version of the Google Closure Compiler (JavaScript minifier) running on App Engine. It has both a user interface and a REST API, which means you can use it as part of an automated build process without needing to set up a local copy of the software. # 9th August 2010, 1:17 pm

TfL Live Traffic Cameras. Part of the new set of APIs released by the Greater London Authority—a list of 177 live traffic camera feeds from around London, all geocoded. # 17th June 2010, 7:14 pm

What’s powering the Content API? The new Guardian Content API runs on Solr, scaled using EC2 and Solr replication and with a Scala web service layer sitting between Solr and the API’s end users. # 24th May 2010, 2:08 pm

GeoPlanet Explorer. Chris Heilmann’s YQL powered explorer for the invaluable Yahoo! GeoPlanet / WhereOnEarth dataset. Every API deserves an explorer of some sort. # 2nd March 2010, 8:14 am

OSM static map api. A very welcome addition to the OpenStreetMap world (with plenty of options for overlaying points, polygons etc) slightly marred by the size and relative ugliness of the OpenStreetMap watermark. # 12th October 2009, 1:37 pm

Cloudvox. A brand new startup offering “API-driven phone calls” with a beautifully simple webhooks based API. # 8th October 2009, 11:31 pm

Google Docs OCR. Whoa, the Google Docs API just got really interesting—you can upload an image to it (POST /feeds/default/private/full?ocr=true) and it will OCR the text and turn it in to a document. Since this is Google, I imagine they’ll also be using the processed documents to further improve their OCR technology. # 29th September 2009, 9:57 pm

Exploring OAuth-Protected APIs. One of the downsides of OAuth is that it makes debugging APIs in your browser much harder. Seth Fitzsimmons’ oauth-proxy solves this by running a Twisted-powered proxy on your local machine which OAuth-signs every request going through it using your consumer key, secret and tokens for that API. Using it with a browsers risks exposing your key and token (but not secret) to sites you accidentally browse to—it would be useful if you could pass a whitelist of API domains as a command line option to the proxy. # 23rd August 2009, 11:06 am

YQL: INSERT INTO internet. insert into twitter.status (status,username,password) values (“Playing with INSERT, UPDATE and DELETE in YQL”, “twitterusername”,“twitterpassword”) # 8th July 2009, 8:19 pm

The Twitpocalypse is Near: Will Your Twitter Client Survive? Twitter tweet IDs will shortly tick over past the maximum signed 32 bit integer, potentially breaking applications. I learnt this lesson when the same thing happened to Flickr photo IDs: never store numeric IDs from external systems as integers, always use strings. # 9th June 2009, 10:52 am

Google Maps Data API (via) I’m disappointed by this one—it’s really just a CRUD store for the KML files used in Google MyMaps. It would be a lot more useful if it let you perform geospatial calculations against your stored map data using some kind of query API—a cloud service alternative to tools like PostGIS. # 20th May 2009, 9:07 pm

resty. 58 lines of bash provides a better command-line interface to RESTful APIs, using curl under the hood. This should save me from running “man curl” several times a week. # 18th May 2009, 1:07 pm

The Little Manual of API Design (PDF). A concise, highly readable guide to designing APIs that are “Complete, Easy to learn and memorize, lead to readable code, hard to misuse, and easy to extend”, based on lessons learnt over many years of development of the Qt framework. # 18th May 2009, 10:14 am

django-piston. Promising looking Django mini-framework for creating RESTful APIs, from the bitbucket team. Ticks all of Jacob’s boxes, even including built-in pluggable authentication support with HTTP Basic, Digest and OAuth out of the box. # 30th April 2009, 7:55 pm

With YQL Execute, the Internet becomes your database. This is nuts (in a good way). Yahoo!’s intriguing universal SQL-style XML/JSONP web service interface now supports JavaScript as a kind of stored procedure language, meaning you can use JavaScript and E4X to screen-scrape web pages, then query the results with YQL. # 29th April 2009, 10:50 pm

Panda Tuesday; The History of the Panda, New APIs, Explore and You. Flickr’s Rainbow Vomiting Panda of Awesomeness now has a family of associated APIs. # 4th March 2009, 11:49 am

Web Hooks and the Programmable World of Tomorrow. Tour de force presentation on Web Hooks by Jeff Lindsay. Tons of really good ideas—provided your application isn’t Flickr sized, there’s a good chance you could implement web hooks pretty cheaply and unleash a huge flurry of creativity from your users. GitHub makes a great case study here. # 16th February 2009, 9 pm