API Discovery: Visibility, Usability, and Advocacy

API DiscoveryVisibility, Usability, and Advocacy
Seeking answers to the Holy Grail question: How do we increase API adoption?
PRESENTED BY:
BILL
DOERRFELD
@DoerrfeldBill
AT:
APIs & IPAs
July 20, 2017

Search Results for 'email API'

Thank you for
watching!
PRESENTED BY:
BILL
DOERRFELD
@DoerrfeldBill
AT:
APIs & IPAs
July 20, 2017
That's how you discover APIs!

This doesn't exist ….. yet
● API Discovery: Can We Do Better?
○ APIs.guru
Mockup:

API Discovery is Fractured
● Size: Over 1700 public web APIs
(ProgrammableWeb, 2017 data)
● Standards: Little consensus on
discovery formats
● Approaches: hand curation,
competing formats, metadata,
directories, specifications.
● SEO: Still your biggest ally
● Word of mouth:

Trends: API Economy Growth
● 17,000+ APIs
● Enterprise
● Impacted sectors:
○ Business
Operations, end
user experiences,
FinTech, DevOps,
"AI," IoT, travel,
shopping, food, etc.

How do you stand out?
How to position service for discovery?
What strategies can we use?

3x3-Tiered Discovery Approach
/usability
/advocacy
/evangelism
/support
/leadership
/seo
/model
/visibility
/directories
/docs
/portal
/dx
GET /marketing

Assumptions
1) You have an API
2) The API is a Product
3) Public API (free or $)
4) Stateless web service
5) More = = =

Visibility
GET /api/marketing/visibility
/usability
/advocacy
/evangelism
/support
/leadership
/seo
/model
/visibility
/directories
/docs
/portal
/dx
GET /marketing

Improve SEO
● A public-facing developer home page has high value.
● To improve SEO, consider:
○ Words: Make human-readable descriptions of functionality.
○ Keyword Frequency: # of target keyword(s) matters!
○ Optimization: Consumer, location, partner.
○ Segmentation: Niche landing pages per service.
○ Tools: Google Adwords Keyword Tool.
○ Content: (more on this in /advocacy )
GET /api/marketing/visibility/seo

Search results for: "Sentiment Analysis API"
COMPANY “TEXT” “ANALYSIS” “API”
Aylien 19 (6%) 11 (3%) 13 (4%)
AlchemyAPI 2 (1%) 2 (1%) 3 (1%)
Text Razor 2 (1%) 2 (1%) 3 (1%)
Bitext 6 (2%) 6 (2%) 20 (6%)
Saplo 11 (3%) 7 (2%) 18 (5%)
GET /api/marketing/visibility/seo
Lessons:
Balance individual
keyword frequency with
keyword variance
Landing page content
matters!
Frequency & % of target keywords in top 5 search results for Sentiment Analysis API

Definition
● What is the Difference Between API
Documentation, Specification, and Definition?
Resources:
GET /api/marketing/visibility/model
● Open source tooling
● Generate client
libraries, SDKs
● Generate
documentation
● Improve
discoverability

Discovery Format
GET /api/marketing/visibility/model
● Like
sitemap.xml
● Include in root
directory
● Little adoption
● 2015
● Swagger, API
Blueprint or
RAML can use
● Reads OpenAPI
specs
● Automatically
searches
● Has API
● "copyright free
sharing and
collaborative
design of API
specifications,
interfaces and
data models."
● APIs.io API
● schemas for
structured
data
● No schema for
API model!

APIs.guru
The Wikipedia of APIs
● https://apis.guru/openapi-directory/
Taken from:
Directory metadata

Taken from:
APIs.guru
The Wikipedia of APIs
Taken from:
Directory metadata
Essentially, It's a REST API to learn
about REST APIs

API Directories (As of July 2017)
1. ProgrammableWeb
2. RapidAPI
3. APIs.guru (OpenAPI Collection)
4. Public-APIs (Github Repo)
5. API List
6. APIs.io
7. SDKS.io
GET /api/marketing/visibility/directories
8. API For That
9. IBM API Harmony
10. Any-API.com
11. API Hound
12. Hitch hq
13. Product Hunt
14. API Katalogen
Profile your API with these sites!

ProgrammableWeb
programmableweb.com
#1
1700 APIs
Hand curated • SDKs & libraries too • news, blogging

RapidAPI
rapidapi.com
#2
Mashape merged • hand curated marketplace • karma rating • track updates
500 APIs

APIs.guru
apis.guru/openapi-directory/
#3
500 APIs
OpenAPI spec • open source • community generated • has API

PublicAPIs
https://github.com/abhishekbanthia/Public-APIs
#4
Github repo • open source • hand-curated of most used
≈ 70 APIs

API List
http://apilist.fun/
#5
≈ 100 APIs
Hand-curated • searchable • new, small directory

• experimental • has API • open source search engine (coming soon?)
APIs.io
http://apis.io
#6
1100 APIs

SDKs.io
http://sdks.io
#7
Pulls from Github, APIs.guru, Mashape, others
30,000+ APIs/SDKs
Definition translation
SDK generation

API For That
http://www.apiforthat.com/
#8
hand curated • niche categories • user-provided input
600 APIs

IBM API Harmony
https://apiharmony-open.mybluemix.net/public
#9
APIs.guru • web crawling • user-provided input
1900 APIs

Any API
https://any-api.com/
#10
APIs.guru • LucyBot • test consoles
≈ 300 APIs

API Hound
http://apihound.com/apifinder
#11
Web crawling • difficult to navigate • comprehensive • can't add API
manually
50,000 APIs

Hitch
https://www.hitchhq.com/apis
#12
docs • SDKs • changelogs • profiles require Hitch account
≈ 800 APIs

Product Hunt
https://www.producthunt.com/
#13
Startups • San Francisco •
manually added • karma ratings
≈ 200 APIs

API Katalogen
http://apikatalogen.se/
#14
In Swedish • civil, open data • APIs are submitted manually
300 APIs

Usability
GET /api/marketing/usability
/usability
/advocacy
/evangelism
/support
/leadership
/seo
/model
/visibility
/directories
/docs
/portal
/dx
GET /marketing

Improve API Documentation
● API docs: public API's best tool
● Point of sale, ongoing support
● Site architecture: 3-Columned,
● Use Definition: Quickly
generate from API definition
○ 30 Doc Solutions (see Resources)
GET /api/marketing/usability/docs
● "3 Ways to Organize Your API Developer Docs"
○ Derric Gilling, Nordic APIs
Resource:

Example: Stripe API
GET /api/marketing/usability/docs

But docs are only part of the picture...

7 Ingredients for a Superb Dev Center
● 7 Ingredients That Make Up a Superb
Developer Center
Resources:
Getting Started Guide Authentication Guide
API Documentation Testing Console
Dev Resources
(code sample, SDK, libraries)
Support Channels
Platform Policy
GET /api/marketing/usability/portal

Cater to All Types of Visitors
● Best Practices in API Documentation,
Smartbear
Credit:
GET /api/marketing/usability/portal

Have good style: Industry best practices
● API Handyman’s API Stylebook
● Zapier Engineering - "API Geriatrics"
Resources:
Endpoints:
logically map to
microservices
REST vs SOAP:
Almost always
REST
URIs: Readable
constructions
Optimization:
Pagination,
Filtering, Ranging.
Data Formats:
JSON over XML,
YAML
Error Handling:
Human readable
responses
CRUD: Correct
HTTP verb
mapping
Hypermedia:
Powerful but
optional
Changelog: All
edits documented
Security: OAuth &
OpenIDConnect
for identity
Versioning:
"Don't" - Roy
Fielding. if u have
to, use
deprecation
headers
Timestamp:
Always use
ISO8601 format
GET /api/marketing/usability/dx

"The effort required to design something is
inversely proportional to the simplicity of the
result. "
-Roy Fielding
Designer of Representational State Transfer (REST)
Inspiration:
GET /api/marketing/usability/dx

Advocacy
GET /api/marketing/advocacy
/usability
/advocacy
/evangelism
/support
/leadership
/seo
/model
/visibility
/directories
/docs
/portal
/dx
GET /marketing

The API Evangelist Playbook
1. Understand userbase
2. Communicate value of product
3. Ensure program is attractive
4. Always be observing, gathering
feedback
5. Host, attend, speak at events
6. Build & maintain an online knowledge
center
7. Translate tech trends
8. Build a community of heroes
● "Day in the Life of an API Evangelist"
○ Nordic APIs
Resources:
GET /api/marketing/advocacy/evangelism

The evangelist routine: Day in the Life
CUSTOMER RELATIONS EVENTS SUPPORT
Social media activity Travel Respond on Stack Overflow
Authoring blog content Host webinars Dev center maintenance
Weekly newsletter Speak at events Test the API
Recognize and award hero developers Research, gather feedback Work on Github helper libraries

Promotion: Where?
• API Blogs
• PW.com, API Evangelist, Dev Weekly Digest, GET
PUT POST, Nordic APIs, dZone, API2Cart
• Social channels
• Hackernews, Product Hunt, Beta List, Stackshare.io,
SubReddits.
• Conferences
• IPAs & APIs, API Strat, REST Fest, API World,
APIdays, Nordic APIs Platform Summit
● http://webapi.events/
Resources:

"The primary role of a developer evangelist in
forming a developer community is to help
customers and potential users see the value and
benefit in your product or API to such an extent
that they themselves become evangelists for
your company."
– Liz Rush
Inspiration:

Form a community: Developer Relations
• Dev outreach increases:
• Awareness
• Understanding
• Vision
• Ways to form a
community:
• Email, chat, forum, conferences,
Knowledge base, blog, content, demos,
use cases
● DevRel: How to Offer Unparalleled
Developer Outreach
Resources:
GET /api/marketing/advocacy/support

Stack Overflow
GET /api/marketing/advocacy/support
● IPinfo.io
● 250 million daily
requests
● One
StackOverflow
response
● $0 budget.

Thought leadership: Evergreen Content
GET /api/marketing/advocacy/leadership
• Less GIFs please
• 18 months
• Extend
• Credible
• Readable

"Either you own the conversation around your APIs
or someone else will."
– Kin Lane
The API Evangelist
Inspiration:

Thought leadership: Own it.
Public apps need to own a
fully-fledged public API
presence.
Otherwise, someone else
will own it.
● Either You Own The Conversation Around
Your APIs Or Someone Else Will
○ -Kin Lane, API Evangelist
Resource:

• "Convincing the Architect"
• Disseminate best practices
• Foster internal culture
• Security
• Agility
• Consistency: Style Guide
Internal leadership: API Intrapreneur

Some other Hidden Truths
GET /api/marketing/extra_advice
/usability
/advocacy
/evangelism
/support
/leadership
/seo
/model
/visibility
/directories
/docs
/portal
/dx
GET /marketing
/extra_advice

Competition: Create Unique Value

Monetization: Free Trial
• Support
developers!
• Increase integration
ease
• Scalable
• Ex. Safety Culture

Provisioning: Release in tiers
Private PublicPartner

"Think of APIs as an evolution...You don’t have to
boil the ocean from day one”
-John Musser, ProgrammableWeb / API Science Founder
Inspiration:

Why consider all this?: A Balanced Release

API Discovery: 15 Ways to Find an API, Nordic APIs
http://nordicapis.com/api-discovery-15-ways-to-find-apis/
4 Methods to Make Your API Truly Discoverable, Runscope
https://blog.runscope.com/posts/4-methods-to-make-your-api-truly-discoverable
Ultimate Guide to 30+ API Documentation Solutions, Slideshare
https://www.slideshare.net/BillConradDoerrfeld/ultimate-guide-to-25-api-documentation-solutions-slideshare-01-69651002
How to Market an API, Nordic APIs
http://nordicapis.com/api-ebooks/how-to-market-an-api/
A guide to RESTful API design: 35+ must-reads, Tech Beacon
https://techbeacon.com/guide-restful-api-design-35-must-reads
Helpful Resources

Slides are up:
@DoerrfeldBill
https://www.slideshare.net/BillConradDoerrfeld/api-discovery-visibility-usability-and-advocac
y

Keep in touch With Nordic APIs!
• Twitter: @NordicAPIs
• Follow our blog: nordicapis.com/blog
• Bi-weekly digest: nordicapis.com/newsletter
• Contributions are welcome!

Nordic APIs eBooks
Marketing Strategy Business Security Platforms
• 10+ eBooks for free download. Examples:

Come out!
Platform Summit • 400 attendees • 50+ speakers

API Discovery: Visibility, Usability, and Advocacy

More Related Content

What's hot

Similar to API Discovery: Visibility, Usability, and Advocacy

Recently uploaded

API Discovery: Visibility, Usability, and Advocacy