I've found that first writing the docs first using API Blueprint has been the single most valuable thing I've done in my API development. It really makes you think about data shape, input params, edge cases etc. and leads to much nicer APIs in my experience. I think it's because, in my case anyway, it's a separate project and language to the implementation, so your thinking is not bound by whatever you're implementing with.
User experience design for APIs
31–40 of 44 posts
Re: User experience design for APIs
#32You cannot build a large API effectively without using it. Programming is tons of details, and you're going to miss some if you aren't programming with your API yourself. It's like building a graphical user interface without ever firing it up.
For instance, if you build a simple REST interface with a list at /object/ and details at GET /object/1 and changes at POST /object/1, then you're good, right? This is a well-understood way of structuring things?
Well, what if your objects are really simple and someone has to synchronize 100k of them. It's not possible to do that efficiently through such an interface.
The API has to see some use, and it has to be able to evolve as you learn. And you need to be ready to make some sacrifices on your side of the fence, to make the life of the API user easier.
Re: User experience design for APIs
#33Before I left Square earlier this year, I lead our design efforts on the developer API. https://docs.connect.squareup.com/ It was really interesting work and the team was quite committed once we found the right team. People always asked what does a designer do on an API. It turns out that if the team cares, quite a lot. Documentation is the obvious one but lots of other things like structuring the actual information,…
It's been years since I've consumed a square API, but I found it amazing when I did. Thank you for your work, even if it came after I used it. Do you think that the Square API hit the level of design just because of the people involved? Or are there organizational factors that played into it? I.e. was good API design seen at the top as a good reason to take longer with a release? I really want to find suggestions to…
A combination.
From the day I started back in 2012 it was clear to me that in order for us to grow functionality to enough verticals in the merchant space we would have to build an API as that was the only way to actually allow for the platform to grow beyond what we could build internally.
It was a hard push for a while though as the focus was in some of the other areas that made us actual money.
The first inception had a pretty strong team but less backup in the organization. We did a lot of great work that never saw the light of day.
Then the last couple of years it all changed and there was suddenly a push to do proper API I was "called into duty" again. This time the foundation was product led rather than tech led and that changed things a lot.
My personal experience was that people just saw API as some technical curiosity rather than as an actual foundation for the business.
Luckily plenty of people in the organization was aware of its importance.
This has changed a lot the last couple of years I think not the least because of Stripes documentation which is almost legendary today.
For some reason, I was always aware of its importance. I even wrote an essay about it back in 2009 and wrote:
"The next big battle is going to be a battle between digital ecosystems; not gadgets, not products and not services.
The most important weapon is going to be the WMCs: Weapons of Mass Connection, a.k.a. the APIs.
These APIs will make it possible for different organizations to have data flow freely between them. Allow for anyone with the right idea to leverage on others’ success without taking anything away from them. On the contrary, the more trusted interpreters you can give access to the data flow, the more robust the digital ecosystem will be."
Re: User experience design for APIs
#34Before I left Square earlier this year, I lead our design efforts on the developer API. https://docs.connect.squareup.com/ It was really interesting work and the team was quite committed once we found the right team. People always asked what does a designer do on an API. It turns out that if the team cares, quite a lot. Documentation is the obvious one but lots of other things like structuring the actual information,…
+1 Perhaps I have said this before, but UX folks have been my go-to colleagues whenever I need their inspsirations for anything ranging from graphs (like monitoring metrics) to debugging since the UX team is heavily involved from the inception of a project and sometimes have more intimate knowledge of the overall architecute of the project than the core developers do. They are amazing (of course I am talking about th…
And I have it the same way with developers. They were always my go-to colleagues more than other designers for insights and
I would generally suggest to hang out with radically different perspectives than your own.
Luckily, in my new company both my partner feel the same way.
Re: User experience design for APIs
#35You cannot build a large API effectively without using it. Programming is tons of details, and you're going to miss some if you aren't programming with your API yourself. It's like building a graphical user interface without ever firing it up. For instance, if you build a simple REST interface with a list at /object/ and details at GET /object/1 and changes at POST /object/1, then you're good, right? This is a well-u…
This. I work in Developer Relations and we used to say our motto was to be the "0th customer". Just by building on top of new APIs we planned to release we'd discover piles of issues and improvements that even the best developers can't spot in the design phase.
Re: User experience design for APIs
#36After three attempts at designing an ML rest-lile API, I ended up writing the deepdetect's API. Never touched its fundamentals since mid 2015. Very very far from perfect but has served great til now!
Re: User experience design for APIs
#37Before I left Square earlier this year, I lead our design efforts on the developer API. https://docs.connect.squareup.com/ It was really interesting work and the team was quite committed once we found the right team. People always asked what does a designer do on an API. It turns out that if the team cares, quite a lot. Documentation is the obvious one but lots of other things like structuring the actual information,…
Great documentation - I am looking to document our own SaaS app API in the coming months, and am inspired to follow Square's lead in terms of style and structure. Did you use a third party documentation CMS for that, or roll your own internally for all the formatting etc.?
A combination. The actual API Reference is using a documentation CMS the other stuff is home-brewed.
Re: User experience design for APIs
#38A few more guidelines that seem obvious to me, but which I see broken all the time:
1) If an API value can be changed any time, it should probably be a plain object property
2) If an API value can be changed but there are side effects, it should probably be a "setFoo" method
3) If an API value can be specified, but not changed after init/instantiation, it should probably be an argument to the constructor or init function
Re: User experience design for APIs
#39You cannot build a large API effectively without using it. Programming is tons of details, and you're going to miss some if you aren't programming with your API yourself. It's like building a graphical user interface without ever firing it up. For instance, if you build a simple REST interface with a list at /object/ and details at GET /object/1 and changes at POST /object/1, then you're good, right? This is a well-u…
This is essentially the argument behind BDD, except applied at a level where the 'customer' is another developer.
Some of the worst APIs I've seen have been ones designed by a backend developer based upon some vague specifications handed down by a non-technical PO. They were often designed with half of the stuff that was necessary missing, lots of stuff that wasn't necessary and some stuff which made no sense before being thrown over a wall.
The better APIs were 'designed' by the developer who would write the code that would consume them. Even if that just meant an email or a scrap of paper with a few example URLs and snippets of JSON.
Re: User experience design for APIs
#40When I worked on the .Net framework at Microsoft we would run usability studies on many of the APIs well before we shipped them. It was always enlightening seeing how professional programmers use your API. We would assume that people would approach the API with a specific mental model for example, only to find that they thought about the API quite differently. I wrote an article in 2004 about how we approached API usability at the time: http://www.drdobbs.com/windows/measuring-api-usability/18440...
The great thing about doing usability studies on APIs is that it is easy to mock up a prototype of the API that people can start to code against. The API doesn't have to work but you get to see how people react to the names of classes, methods, parameters etc. I used to blog about API usability and what we were learning here: https://blogs.msdn.microsoft.com/stevencl/tag/api-usability/
There is a group of researchers and practitioners currently working on API usability. Some good links here: http://www.cs.cmu.edu/~NatProg/apiusability.html