SlideShare uses cookies to improve functionality and performance, and to provide you with relevant advertising. If you continue browsing the site, you agree to the use of cookies on this website. See our User Agreement and Privacy Policy.
SlideShare uses cookies to improve functionality and performance, and to provide you with relevant advertising. If you continue browsing the site, you agree to the use of cookies on this website. See our Privacy Policy and User Agreement for details.
Successfully reported this slideshow.
Activate your 30 day free trial to unlock unlimited reading.
So, you have an API! Should you leave it at this or also offer a client library/SDK? Using examples from other API providers, this talk will help you decide. We‘ll look at good practices for designing and documenting APIs as well as SDKs, to achieve good developer experience, no matter which choice!
This talk was held at "API the Docs" in Paris on April 24th, 2018.
https://apithedocs.org/paris2018
Transcript
1.
@LukasRosenstock
To SDK … or
not to SDK?
2.
API abbr. Application Programming Interface n.
A remote interface available over HTTP(S),
designed in a REST or RPC style.
3.
SDK abbr. Software Development Kit n.
A software library with the primary purpose
of wrapping an API for a specific language.
4.
Server-2-Server Integrations
Server
Client
(web/native)
Third Party
Service
SDK
API
API
9.
Are SDKs really necessary?
And if not, why do I feel API providers force them on me?
10.
For API Consumers
“SDKs introduce a complexity
cost over the lifetime of your
app that outweigh the gain of
not having to rewrite the code."
John Sheehan, Runscope (CA Inc.)
11.
For API Providers
●
SDKs are additional effort →
– You can‘t have SDKs without APIs!
●
Is it worth it?
12.
Coming up:
●
Advantages of SDKs
●
SDK Strategy
– Four Patterns
– Suggested Approach
●
Good SDK Design
●
Documenting APIs & SDKs
– Approahches
– Top API Provider Portal Showcase
●
Conclusion
13.
Advantages of SDKs (1)
●
Beginner Friendly
– Easier to support!
15.
Advantages of SDKs (3)
●
Insights into API
usage from different
languages
– User Agent
– Monitoring
●
Opportunity to
connect with the
programming
community
16.
Definitions from discussions
at APIStrat conference, 2016
SDK Strategy: Four Patterns
●
Provider-supported
●
Community-contributed
●
Consumer-driven
●
HTTP is the SDK
17.
SDK Strategy: Suggested Approach
Design a great API
OpenAPI
Document it well
Release your spec
Embrace community SDKs
Release your own SDKs
TIME
18.
Interlude
„Whatever people
can pull down from their
favorite package manager
is their developer experience.“
Cristiano Betta at APItheDocs
December 2017 in Amsterdam
19.
Good SDK Design (1)
●
API Design comes first
– Add value over the API
– SDKs can‘t cover up bad APIs
●
Open Source is a MUST
●
Make SDK development a part of API testing
20.
Good SDK Design (2)
Respect your target platform‘s approach first,
consistency within your API second.
21.
Interlude
●
Can I auto-generated my SDKs?
– (+) Achieves presence and standardized
approach
– (-) No business-specific value-add
22.
API & SDK Documentation
●
API-first, SDK-second
●
SDK-first, API-second
●
Integrated
●
Tutorials vs. Reference – different approaches
– Consistency?
24.
Conclusion
●
Provide SDKs if you can and believe there‘s
additional value or you want to support
beginners.
●
Don‘t forget the API over SDKs! Design both
well and respect them in your portal.
So, you have an API! Should you leave it at this or also offer a client library/SDK? Using examples from other API providers, this talk will help you decide. We‘ll look at good practices for designing and documenting APIs as well as SDKs, to achieve good developer experience, no matter which choice!
This talk was held at "API the Docs" in Paris on April 24th, 2018.
https://apithedocs.org/paris2018
Transcript
1.
@LukasRosenstock
To SDK … or
not to SDK?
2.
API abbr. Application Programming Interface n.
A remote interface available over HTTP(S),
designed in a REST or RPC style.
3.
SDK abbr. Software Development Kit n.
A software library with the primary purpose
of wrapping an API for a specific language.
4.
Server-2-Server Integrations
Server
Client
(web/native)
Third Party
Service
SDK
API
API
9.
Are SDKs really necessary?
And if not, why do I feel API providers force them on me?
10.
For API Consumers
“SDKs introduce a complexity
cost over the lifetime of your
app that outweigh the gain of
not having to rewrite the code."
John Sheehan, Runscope (CA Inc.)
11.
For API Providers
●
SDKs are additional effort →
– You can‘t have SDKs without APIs!
●
Is it worth it?
12.
Coming up:
●
Advantages of SDKs
●
SDK Strategy
– Four Patterns
– Suggested Approach
●
Good SDK Design
●
Documenting APIs & SDKs
– Approahches
– Top API Provider Portal Showcase
●
Conclusion
13.
Advantages of SDKs (1)
●
Beginner Friendly
– Easier to support!
15.
Advantages of SDKs (3)
●
Insights into API
usage from different
languages
– User Agent
– Monitoring
●
Opportunity to
connect with the
programming
community
16.
Definitions from discussions
at APIStrat conference, 2016
SDK Strategy: Four Patterns
●
Provider-supported
●
Community-contributed
●
Consumer-driven
●
HTTP is the SDK
17.
SDK Strategy: Suggested Approach
Design a great API
OpenAPI
Document it well
Release your spec
Embrace community SDKs
Release your own SDKs
TIME
18.
Interlude
„Whatever people
can pull down from their
favorite package manager
is their developer experience.“
Cristiano Betta at APItheDocs
December 2017 in Amsterdam
19.
Good SDK Design (1)
●
API Design comes first
– Add value over the API
– SDKs can‘t cover up bad APIs
●
Open Source is a MUST
●
Make SDK development a part of API testing
20.
Good SDK Design (2)
Respect your target platform‘s approach first,
consistency within your API second.
21.
Interlude
●
Can I auto-generated my SDKs?
– (+) Achieves presence and standardized
approach
– (-) No business-specific value-add
22.
API & SDK Documentation
●
API-first, SDK-second
●
SDK-first, API-second
●
Integrated
●
Tutorials vs. Reference – different approaches
– Consistency?
24.
Conclusion
●
Provide SDKs if you can and believe there‘s
additional value or you want to support
beginners.
●
Don‘t forget the API over SDKs! Design both
well and respect them in your portal.