Companies eager to join the API economy often fail in a couple of vital areas. While the functionality of their services may be impeccable, rookies don’t always frame them in a way that beckons more usage.
Here are some common anti-patterns that could be hindering API or SDK adoption for public-facing developer programs. And for each pitfall, here are few healthier strategies that will help providers bolster their API adoption rates. (Even though the advice below will focus on what makes public APIs more appealing, many of the same guidelines can apply to internal API development as well.)
1. Documentation has bad design
Documentation is continually cited by professionals as a public API’s best tool. Great API docs act as both the point of sale and the focal point between developers and the API provider. But what happens if documentation is poorly designed or inaccessible?
To maximize exposure, use easily traversable docs with quality user interface design, and provide playgrounds for sampling API methods and responses. Using a three-column layout, the Stripe developer center is a model for attractive API documentation. Given an API specification such as OpenAPI or RAML, it offers over 30 tools to generate similarly slick docs that will impress visitors.
2. API provider didn’t consider the developer experience
If there is a signup wall between consumers and the documentation, it’s not a public API. While some enterprises get nervous about providing free and open-source resources, public docs are a necessary element for evangelizing a public API.
Slow API adoption could also stem from the API’s core. RESTful APIs that send JSON packages over the HTTP protocol are currently the industry standard. API product owners entrenched in SOAP and XML doctrines may have a difficult time assuaging new consumers, who have expectations for REST and for even more bleeding-edge approaches, such as GraphQL.
Making the service easily consumable with implementation guides, test sandboxes, and helper libraries in many languages is a sure way to promote use. As you continue to promote your API, you need to constantly be aware of current programming trends so that you can continue to bring it in line with developer needs and expectations.
3. API provider didn’t lead the developer community
A thriving knowledge base of API consumers can be vital for disseminating quality information, and community forums can cut down the time a team spends on one-on-one support. Not to mention, word of mouth is the greatest tool for marketing.
However, organizations should never expect a community to form out of thin air. The API providers that successfully create a thriving public knowledge base not only build out a forum space but are also the first to generate discussion on the forum.
Shopify, for example, fosters its developer community, putting developer relations in the forefront of its API strategy with three support teams, active forum participation, and discussions it leads at in-person events.
4. API construction doesn't follow best practices
APIs that don’t follow some standardized best practices can instantly turn developers off. This could be unsavory URI design, complex versioning that routinely breaks clients, bad call mapping, or a lack of optimization of the response package with pagination. Other malformed design patterns that can also stigmatize growth include:
- Mapping CRUD to incorrect HTTP verbs
- Opaque status codes and error responses
- Unreadable URI design. For example, 'api.example.org/user/128485959923adsfasdf' is quite illogical in comparison to 'api.example.org/user/doerrfeldbill'
Though true RESTafarians advocate for HATEOAS-compliant APIs, simply developing with usability (and longevity) in mind can go a long way toward minimizing the implementation hurdle.
5. The front end does not cater to non-devs at all
If the developer portal isn’t human-readable, then designers, entrepreneurs, and business leaders can’t see the value in it. This eliminates a huge potential market of influencers.
To cater to a wider spectrum without losing technical validity, a public web API’s front end must include descriptive copy on feature sets, example use cases, and testimonials, and links to developer code examples. Consider how Box describes its cloud content management API suite for all parties—landing pages such as this embody the idea that providers must treat their API as a product.
6. The service is not discoverable
What is the point of having an API if it can't be found? Profiling your service in API directories such as ProgrammableWeb, APIs.guru’s OpenAPI directory, RapidAPI, APIs.io, and many others can widen the reach of your service into new communities. Likewise, improving SEO with target keywords on developer portals and generating an APIs.json file can improve discoverability with search engines.
While setting up a service to be found is important, it’s still too passive. Developer advocacy—or evangelism—is now a necessary component in marketing an API program. A true developer evangelist is in tune with the needs of the API provider's user base, communicates their stories, and continually publishes thought leadership content to advance the entire industry.
7. The platform is not secure
An API provider that solely relies on HTTP Basic Auth or API keys for access is putting its program in jeopardy. Securing API access with OAuth 2.0 Authentication and delegating credentials with OpenID Connect has become the standard for API platforms.
With large-scale domestic and foreign cyber breaches continually making headlines, an insecure integration could (and should) be a major deterrent for third-party viewers.
8. Provider does not pay attention to the competition
While a major pivot is not an easy fix, it’s important to consider where your competition lies. Now that the API economy is so diverse, hundreds of niche web APIs exist that probably provide functionality similar to yours, which can stunt usage if the grass is greener on the other side.
This is especially true for business processing outsourcing (BPO) data and functionality services, such as payment processing, cloud computing, telecommunications, e-commerce, transportation data, or sentiment detection. Companies that are devoted to promoting an API as their sole product will find a hard road ahead if they don’t assess the current landscape.
If there’s already a competing API service, this could warrant a pivot in the features set to focus on expansion or refining a niche expertise area. This could necessitate a pivot in user base, such as a provisioning move from public to partner, or a target consumer change from enterprise to startup.
Give some API TLC (time, love, and care)
An API left alone will not grow. It requires constant attention to evolve. Igniting developer engagement is important, but other factors such as unscalable API calling rates or high-cost models could be just as relevant deterrents that can result in a frozen program.
APIs continue to become ever-more important factors in web software as drivers of crowdsourced development and business value. Furthermore, as their role is solidified in the Internet of Things (IoT) economy of tomorrow, low-use programs shouldn’t give up easily.
With that in mind, platform architects running a low-performance API must consider how to make the program more palatable to developers and non-developers alike. Watch your analytics closely, and heed these cues to iterate your program—and do so way before throwing in the towel.
Keep learning
Take a deep dive into the state of quality with TechBeacon's Guide. Plus: Download the free World Quality Report 2022-23.
Put performance engineering into practice with these top 10 performance engineering techniques that work.
Find to tools you need with TechBeacon's Buyer's Guide for Selecting Software Test Automation Tools.
Discover best practices for reducing software defects with TechBeacon's Guide.
- Take your testing career to the next level. TechBeacon's Careers Topic Center provides expert advice to prepare you for your next move.
