The Making of an API

I’m happy to announce that we’ve released a new API for our partners and customers. The API allows you to access the job opening and application information in your HiringThing account, and enables a number of different use cases.

You can get started with the API by reading our online documentation.

It became clear to us that we needed an API over the last few months. We’ve been getting a few requests for integration with other systems, and beyond custom development, didn’t have a good answer. With a robust and well documented API, we effectively open the doors to any customer that wants to tinker with their HiringThing data, and makes it easy to integrate with other applications.

How We Built It

We started off, quite simply, by studying the APIs that we’ve used that we admire. Some great ones specifically – Chargify, Wufoo and Mailchimp. Everyone has slightly different opinions on how APIs should work (and there’s much contentious debate,) but we had a few features we knew we wanted to prioritize:

  • Easy to understand and implement for developers. Having implemented a fair number of APIs ourselves, we know first-hand that any barriers to implementation can stop a project cold.
  • Modern http-based approach (no SOAP). In our opinion, many “enterprisey” integration techniques are needlessly complex and hopelessly over-engineered. Enough said.
  • Solid security. Obviously the security of our customer’s data is an overarching priority. We’ve taken pains to ensure that encryption and access control are all carefully managed to high industry standards.
  • At least one client library available at launch. It’s a hundred times easier to implement an API when there are libraries for your language of choice. We’ve started with a Ruby gem hiringthing-api, and hope to be expanding the list of available libraries over time.

I’m happy to say we met all our goals. A few tips we learned along the way.

  • Documentation. One of the best things we did is start with the documentation, and get that peer-reviewed, before we wrote a line of code. This helps ensure that your API approach is consistent and logical, and ensures that implementation shortcuts don’t influence your interface design.
  • Security. Security can be tricky, and there are different levels of security needed for, say, nuclear missle codes than we might need here. That said, we want to ensure that data is at least as secure as your average online credit card transaction. All API access to HiringThing is encrypted with SSL and uses both an API key and password to authenticate. Also, the API can be turned off at any time, or new access keys can be generated that will invalidate the previous set.
  • Client Software. The desire to have a client library available out of the box definitely helped us with the overall API development. We built the hiringthing-api, Ruby gem to the API documentation, before we wrote the API code, which again helped us validate our direction and ensure correctness in our implementation.
  • Tests. As a final step (and something we do with all HiringThing code), we wrote a robust set of tests that validate that various API functions work as expected. I can’t say enough about how helpful test-driven development practices have been at HiringThing.

The last step was actually to write code! But, with all the groundwork laid above, it was the easiest part. Rails makes it fairly easy to implement an API like this, although we declined to use some of their built-in patterns and RESTian tools.

How to Enable the API

It’s easy to get started. First, of course, you’ll need a HiringThing account. (get started with our 30-day free trial) Once you’re logged in, navigate to Account Details, and then to the Data tab.

Click enable to turn the API on. You’ll see an API Key and API Password, these are the credentials you’ll need to access your account via the API.

Access will now be available on your HiringThing domain.

https://<your-subdomain>.hiringthing.com/remote/<entity endpoint>

Get started with our online documentation. If you’re using Ruby, start with the gem hiringthing-api, which makes API access incredible easy.

Written by

Joshua Siler is the Founder and CTO of HiringThing, an online application provider dedicated to changing the way small and medium businesses hire talent. You can learn more about HiringThing at http://www.hiringthing.com.
blog comments powered by Disqus