Designing for the Platform — API design

joe russo
3 min readMar 29, 2017

In our last entry we talked about the object models you need to consider in your design work, and there are two. The System Object Model and the User Experience Object Model.

Now we can use these to design our API. Since we’re focused on the Platform being a Cloud Platform, we have three areas to work through in API design. They are Service API, Application Extensions and Embeddable UX.

First, let’s look at the Service API. This is the API’s we provide to a developer to make use of the System Object Model. We don’t really know what that developer wants to build, but we do know our own system so we can craft the API to allow them enough valuable interactions to do whatever it is they wish to do.

We’ll go back to our example of the simple To Do (Task) system we used in our last entry. Our model allows for Task objects, with properties like due date, etc…here’s the picture from last time.

We can create a pretty straight forward list of what we need here, we need API’s for;

  • Create a task
  • Delete a task
  • Update a task’s state
  • Update a task’s due date
  • Update a task’s description
  • Update a task’s assigned-to entry
  • Update a task’s created date
  • Update a task’s created by entry
  • Get a Task

Hmm…kind of a tedious list and do we really want to let someone change the created by entry? Or creation date? Let’s examine this.

First, having those 6 Update API’s that are very focused on one specific thing are nice and straightforward to the developer. But, let’s say the developer wants to change 3 of these, they have to make 3 calls to make that happen. Doesn’t sound like much, BUT it’s tripling the burden to the developer, the performance of his code (that is, tripling the impact to performance) and it’s tripling the load on our server. If you’re really successful and have 1000’s of apps built on your service this can turn into a crisis.

We could decide to just make four API’s in total;

  • Create a task
  • Delete a task

--

--

joe russo

Designer, developer, writer, soccer fan, traveler, lover of food and cooking, quantum computing geek.