Developer Portals: when Docs become DX

Developer Portals Technology

Developer Portals: when Docs become DX

March 29, 2018

Developer portals play not only a technical role, they also play a somewhat obscure commercial role. We don't like to say that this is a commercial site, but actually it is also about promotion. You have to explain what you do – preferably not in a hard-core manipulative way. For that, you need more than reference docs. How to get started? What does that API do? A lot more than just the very technical aspects need to be explained.

A less well circulated purpose of developer portals is their being a trust signal. They engender trust by showing how much investment went into building that portal. They have to show that the API services documented on that portal will keep on existing and will get reliable support long term.

Read more
Treat docs like code

Technology

Treat docs like code

July 27, 2017

On the Write The Docs London meetup in January speakers from leading Git code repositories talked about how their teams dogfood their own tools to do their documentation. Version the Docs covered Bitbucket and GitLab, but we missed a GitHub presentation. To fill this gap, we interviewed Anne Gentle about GitHub, treating docs like code, and community contributions to documentation.

Read more
Upstream Developer Experience: a Role for Developer Portals in Enterprise API Design - Developer Portal Strategy Part 3

Developer Portals Technology

Upstream Developer Experience: a Role for Developer Portals in Enterprise API Design - Developer Portal Strategy Part 3

May 10, 2017

Most of the time when we talk about developer experience, we mean downstream DX, the experience of developers that implement APIs. But what about the developers that create APIs? In a previous post we wrote about the 8 stakeholders of developer portals, we argued that while the developers that use APIs are important, we shouldn’t forget about the experience of other stakeholders of a developer portal. In this post I’ll explore the experience of one of these audiences - the API developers - and explain what upstream DX is, when it matters, and how you can use a developer portal to improve it.

Read more
Documenting web APIs with the Swagger / OpenAPI specification in Drupal

Developer Portals Technology

Documenting web APIs with the Swagger / OpenAPI specification in Drupal

April 20, 2017

As part of our work to make Drupal 8 the leading CMS for developer portals, we are implementing a mechanism to import the OpenAPI (formerly known as Swagger) specification format. This is a crucial feature not only for dedicated developer portals, but also for all Drupal sites that are exposing an API. Now that it has become much easier to create a RESTful API service in Drupal 8, the next step is to make it more straightforward to create its API reference documentation. That is why we think our work will be useful for site builders, and not just for technical writers and API product owners.

Read more
Web APIs in Drupal: success takes more than an endpoint

Developer Portals Technology

Web APIs in Drupal: success takes more than an endpoint

March 23, 2017

Web APIs are not just useful when making headless sites in Drupal: large Drupal sites often hold valuable information that could also be useful outside the site's context. Media companies might want to expose historical media content, community sites could show data about their community activities, e-commerce sites tend to open an API for their affiliates and partners.

While it is possible to use Drupal 7 and Drupal 8 as an API backend, a lot of functionalities that describe a mature API service do not come out of the box. In this post we will explain what key concepts you have to keep in mind when designing an API service, why they are important and how APIgee Edge can make it easier to build a full-featured API webservice in Drupal successfully.

Read more