How do we increase API adoption? One method is by making the web service more discoverable. In this presentation, I explore 3 areas of API marketing; visibility, usability, and advocacy. In it, I outline discovery formats and API definitions that can help create more usable front ends. I list the the API directories and marketplaces that catalog REST services to make your interface more findable. Also, I describe best practices for crafting usable APIs, and strategies top evangelists deploy to build effective developer communities that convert developer visitors into developer users. Given at the Nordic APIs Platform Summit 2017.
Beginners Guide to TikTok for Search - Rachel Pearson - We are Tilt __ Bright...
API Marketing: How to Make Your API More Discoverable
1. API Marketing:
How to Make Your API More Discoverable
Seeking answers to the Holy Grail question: How do we increase API conversion?
PRESENTED BY:
BILL
DOERRFELD
@DoerrfeldBill
AT:
Nordic APIs
Platform
Summit
Oct 10, 2017
5. Thank you for
watching!
That's how you discover APIs!
PRESENTED BY:
BILL
DOERRFELD
@DoerrfeldBill
AT:
Nordic APIs
Platform
Summit
Oct 10, 2017
6.
7. This doesn't exist ….. yet
● API Discovery: Can We Do Better?
○ APIs.guru
Mockup from article:
8. API Discovery is Uncertain
● Size: Over 1800 public web APIs
(ProgrammableWeb, 2017 data)
● Standards: Little consensus
● Varying Categorical Approaches :
hand curation, automated, metadata,
directories, using specifications.
● SEO: Still your biggest ally
● Word of mouth:
9. Trends: API Economy Growth
● 18,000+ APIs
● Enterprise
● Impacted sectors:
○ Business
Operations, end
user experiences,
FinTech, DevOps,
"AI," IoT, travel,
shopping, food, etc.
10. How do you stand out?
How to position service for discovery?
What strategies can we use?
14. 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
15. 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
16. 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
17. Discovery Formats
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!
20. 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!
36. 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:
39. 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
40. Cater to All Types of Visitors
● Best Practices in API Documentation,
Smartbear
Credit:
GET /api/marketing/usability/portal
41. 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
42. Dynamic Behavior (Discoverability)
GET /api/marketing/usability/dx
● Exchange between client & server
● Client scopes
○ may limit which operations are
available to an app;
● User permissions
○ may limit operations
● HATEOAS
○ Hypermedia APIs allow
exploration/navigation
○ Provide responses to GET/POST calls
43. "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
45. 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
46. 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
GET /api/marketing/advocacy/evangelism
47. 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:
GET /api/marketing/advocacy/evangelism
48. "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 API to such an extent that they
themselves become evangelists for your
company."
– Liz Rush
Inspiration:
GET /api/marketing/advocacy/evangelism
49. Form a community: Developer Relations
• Dev outreach increases:
• Awareness
• Understanding
• Share vision
• Ways to form a
community:
• Email, chat, forum, conferences,
Knowledge base, blog, content, demos,
use cases
• Shopify
● DevRel: How to Offer Unparalleled
Developer Outreach
Resources:
GET /api/marketing/advocacy/support
51. Thought leadership: Evergreen Content
GET /api/marketing/advocacy/leadership
• Less GIFs please
• 18 months
• Extend
• Credible
• Readable
52. "Either you own the conversation around your APIs
or someone else will."
– Kin Lane
The API Evangelist
Inspiration:
GET /api/marketing/advocacy/leadership
53. Thought leadership: Own it.
GET /api/marketing/advocacy/leadership
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:
54. 1. Create an API definition
2. Leverage API discovery formats to make your API
machine readable
3. Profile your API in the growing number of API directories
4. Improve SEO with target keyword copy in developer
home pages & docs
IN SUMMARY
4 ways to make your API more discoverable
57. API Marketing:How to Make Your API More Discoverable
PRESENTED BY:
BILL
DOERRFELD
@DoerrfeldBill
AT:
Nordic APIs
Platform
Summit
Oct 10, 2017
58. 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