Engineering

We've been busy improving our APIs based on your feedback, and I'm excited to announce a few additions we've just shipped. Versioning The biggest change is the addition of versioning to our APIs. We use a date based version which you can pass through in a API-Version header when making API requests. curl 'https://person.clearbit.com/v1/people/email/alex@clearbit.com' \ -H 'API-Version: 2015-05-11' All of our clients support setting a version. For example with our Ruby library: Clear

Versioning APIs is never fun but if you provide a public API it's something you'll almost certainly run up against eventually. At Clearbit we've just started adding breaking changes to our API and have had to start thinking about how we're going to approach versioning. There seems to be a few main approaches that people have tried: Use the URL This is a fairly straightforward solution - simply add an incrementing version number in the URL and route different API versions to different endpoints

Heroku [http://heroku.com] is an awesome component to the developer toolchain and lets you get something up and running easily. For me at least, it's transformed how I think about and architect applications. However, there are also a lot of reasons why you might choose an alternative. Maybe it's speed, control, or maybe you just like tinkering. For us, the reason was cost--pure and simple. Clearbit has a huge cluster of machines crawling the web, and Heroku would have been prohibitively expensi

PostgreSQL is notoriously bad at performing well with high offsets, mainly because it needs to do a full table scan and count all the rows up to the offset. This can be a problem is you want to paginate over a full table without holding all the rows in memory. On the surface of it PostgreSQL Cursors [http://www.postgresql.org/docs/9.2/static/plpgsql-cursors.html] may seem like a good solution to this problem--rather than executing a whole query at once a cursor encapsulates the query allowing y

We're excited to announce some new API features based on some of the feedback we've received from our customers. Streaming Some of our endpoints respond asynchronously. For example, when we look up an email, if we haven't cached the lookup, we'll need to go out and search our indexes. This can take in the region of five to ten seconds. If we have to respond to a lookup asynchronously then we'll return a HTTP status 202 code and ask you to either retry the request later or use our webhook API [