Teamleader Blog Article

Teamleader API: why did we choose an RPC architecture?

Teamleader API: why did we choose an RPC architecture?

"Why isn't your new API based on REST architecture? Isn't that the standard nowadays?" That's probably the most recurring feedback we heard when discussing our new API. A justifiable remark, and we'd love to give you a quick answer.

"We wanted an API that made sense from a human point of view, instead of starting from the technical side."

20171212_API_Inline1_producttoplatform.jpgWhen we designed our new API, we wanted to uphold a number of basic principles: the software had to be scalable enough (and thus also futureproof), and the logic behind it was very important. We wanted an API that made sense from a human point of view, instead of starting from the technical side. If you want to use the API, that should be an intuitive process, just like you would do something in real life.

No REST for the wicked

That also explains why we didn't go with a REST architecture. There's nothing wrong with REST per se. For some purposes, it is the right choice without any doubt. In spite of the many variations, it has gradually grown into the staple for this type of projects.  In other words: we could've made our lives easy by choosing REST.

By making our lives slightly harder, we chose to make the lives of our end user easier instead.

We deliberately chose not to go that way. By making our lives slightly harder and not applying a REST architecture, we make the lives of our end users a lot easier. REST forces you to use a specific terminology which often deviates from what you're used to - and can feel very inflexible. Moreover, in this type of architecture, it's not that simple to display the changing status of an object. And in software like Teamleader, where everything is about flows or processes, changing statuses are the norm rather than the exception.  Just think of invoices, that can be booked, paid or credited.

20171212_API_Inline2_RPC.jpgREST has its limitations

An API based on REST architecture is also much more complicated - so most companies prefer one of the many variants. it's not always clear what will happen behind the scenes once you change certain items. A REST API, for instance, often introduces properties that do not match the reality of your software (e.g. changing the status of an invoice in Teamleader). The side effects of such a change (or the properties it entails) are not always straightforward.

In our action-oriented API, we chose to leave out these fields, and build exceptional API endpoints to help you complete these actions. This way, you'll always know you're doing something that requires mandatory values. Think of the invoice number when booking an invoice, the amount when recording a payment, or the date when planning a task.

Choosing RPC

20171212_API_Inline3_accessible.jpgSo: out REST, in RPC. Why exactly? REST works really well for CRUD operations (Create, Read, Update and Delete). But if you need to complete different actions, such as booking an invoice or linking a contact to a company, a different model will quickly be much more user-friendly. We were inspired by Slack - that use a more action-oriented RPC approach. Their way of working ties in better with Teamleader too, as we prefer clarity over technical terms introduced to follow certain standards.

The main advantages?

  1. Actions are clear, and not hidden in properties as is the case with REST. You'll always know which data to add to which action and what that action will do to your 'object'. Clearer, more predictable, and therefore also more reliable.
  2. There's no need for technical terminology to adhere to specifications. Translating all actions in Teamleader to REST endpoints would be a Sisyphean task - and they would also be harder to understand.

The main objection: developers are used to REST APIs. But we're convinced any developer will get used to this new approach quickly, as soon as you go through the basic principles at developer.teamleader.eu.

Change is never easy - but we wouldn't be developers if we blindly held on to principles from the past. As soon as you get started with our new API, you'll notice RPC was the right choice.