A short, concise, portable description of what your API does, is one of the most critical building blocks of API management, and is essential to reducing friction when new users are on-boarding with any API. It can be easy to design, and populate your API developer portal from a perspective that is very much in the know. I do it all the time, structuring your portal to reach the widest possible audience can be hard—it is why I’m here! ;-)
Here is a great example of providing all the right elements, but leaving out the essential detail that new API consumers will need. View the Dailymotion developer area, land on home page, and without clicking, tell me what Dailymotion does.
The portal has all the right moves, except it neglects to say anything about videos, or show a video picture. I guess you could argue that anyone landing here will probably be getting there via the main Dailymotion site, with the proper knowledge of what is going on. This is probably true, but there will always be people landing on the API developer portal page, without any clue of what Dailymotion does—do not make them click to find out.
This really isn’t that big of a mistake, and something that only someone like me, who looks at numerous developer portals would think about. For Dailymotion, all they have to do is update the FMA area, put video in the title, short description, and maybe include as an image in the background. Boom, within seconds everyone understands the value offered by Dailymotion in 2 seconds or less.
The description you provide on your API portal landing page is your first impression, make it count. It is also likely, that the press, bloggers, and other 3rd parties will copy / paste the description to describe what you do, on remote websites—so make it good!
