How *not* to design an SDK

Talk about good API and SDK design practices

Transcript

1. How *not* to design an SDK IMHO
2. who? • Javier Gamarra / @nhpatt / nhpatt.com • @cylicon_valley (19-21/05|04/06) / @agilespain (01-02/07) • @liferay • java/javascript
3. an SDK
4. a set of tools to create applications
5. liferay has *many* SDKs...
6. Plugins SDK
7. Mobile SDK
8. Push SDK
9. Screens
10. Portal/DXP
11. why?
12. fast development
13. “because your API sucks” -- mailchimp
14. “because your my API sucks” -- me
15. insert random unicorn here April's unicorn birthday with 31 flavors of Baskin Robbins.
16. “maybe you should start fixing your API?” -- me
17. your SDK *is* the API
18. design
19. choose your target wisely
20. Select your audience • Mobile developers vs Liferay developers • Android vs iOS • Uniform API vs divergent
21. reduce friction
22. your SDK should be up in <5 minutes with <10 lines of code
23. Fabric
24. Android Push
25. • Don’t be like the Android SDK ◦ Only if you have a captive audience :P • Give feedback in each step • Follow the platform conventions (jcenter/cocoapods) Reduce friction
26. Reduce friction
27. the best step to install is no step
28. do 1 thing or several?
29. do 1 thing and several
30. Do 1 thing and several • Modular compile project(':liferay-screens’) compile project(':liferay-material-viewset') compile project(':liferay-westeros-viewset') compile project(':listbookmarkscreenlet') • Enable features with builders
31. Do 1 thing and several If you become a “Bag of things” you’ll need the be the best bag of things
32. And do it well
33. real use case
34. how
35. hide complexity
36. Hide complexity • Don’t introduce new concepts (or just a few) • Hide internal concepts and problems • Don’t do this: public BasicEvent(int targetScreenletId, Exception exception) { _targetScreenletId = targetScreenletId; _exception = exception; }
37. customization
38. do not force the user
39. do not be opinionated
40. do not be opinionated (outside)
41. Allow extension and customization Don’t restrict your users: The SDK should be extensible Allow advanced use cases
42. Classes should be extensible • Use callbacks • Interfaces to allow extension • Fluent interfaces with builders • Factories • Strategy pattern • Template methods • Custom implementation
43. Callbacks Use callbacks/listeners to notify the developer loginScreenlet.setListener( this); @Override public void onLoginSuccess(User user) {info( "Login successful!");} @Override public void onLoginFailure(Exception e) { error( "Login failed", e);}
44. Interfaces Use interfaces to allow extension public interface CredentialsStorage { void storeCredentials(); void removeStoredCredentials(); boolean loadStoredCredentials() throws IllegalStateException; }
45. Builders Interact with the SDK with a fluent interface through builders CredentialsStorage storage = new CredentialsStorageBuilder() .setContext(context) .setStorageType(storageType) .build();
46. Factories return (ServiceVersionFactory) Class.forName(getVersionFactory()) .newInstance();
47. Custom implementations public void initWithCustomStorIOSQLite( DefaultStorIOSQLite defaultStorIOSQLite) { _storIOSQLite = defaultStorIOSQLite; }
48. but the most important part is the UI
49. • Force one • Let the developer implement it • Provide a default and allow overriding UI?
50. UI Pass a layout, use a viewmodel (interface) as a contract and provide a default <com.liferay.mobile.screens.webcontent.display.WebContentDisplayScreenlet android:layout_width= "match_parent" android:layout_height= "wrap_content" liferay:layoutId="@layout/webcontentdisplaystructured_example"/>
51. UI • Follow platform conventions • Colors with the primary scheme • Themes with default layouts and colors • Layouts (defaults) overridden by android conventions
52. Use sane defaults Allow the developer either to use this: <com.liferay.mobile.screens.webcontent.display.WebContentDisplayScreenlet android:layout_width="match_parent" android:layout_height="wrap_content"/> Or that: <com.liferay.mobile.screens.webcontent.display.WebContentDisplayScreenlet android:layout_width="match_parent" android:layout_height="wrap_content" liferay:articleId="@string/liferay_article_structured_article_id" liferay:labelFields="@string/liferay_articles" liferay:layoutId="@layout/webcontentdisplaystructured_example" liferay:offlinePolicy="REMOTE_FIRST" liferay:structureId="@string/liferay_article_structured_structure_id" />
53. easy to use, hard to misuse
54. don’t be like liferay
55. unicorn search
56. do not “learn liferay” do not “learn your SDK”
57. Easy to use • Follow language idioms • Always be compatible with latest versions • Watch out environments (liferay vs android)
58. Easy to use The Android SDK (or iOS) shapes your library: • Orientation problem? (hide!) • Permissions (simplify!) • Dependencies (watch out…) • Sync vs async (be opinionated inside!) • Solve common problems (like cache layer) • Component oriented (or application class)
59. Hard to misuse • Support null arguments • Gracefully degrade • Catch unexpected exceptions (and inform the user consistently)
60. document everything
61. • Tutorials (task oriented) • References • Javadocs • Forums (and bug tracker!) • Youtube Document everything
62. Sample Apps
63. LOTS OF THINGS TO TALK
64. focus your efforts in acquiring users
65. *be* the developer
66. questions?
67. References • Client library design • Best practices for ios api design • Building first class Android SDKs
68. How to *not* design an SDK IMHO
69. versions
70. “Programming is a little bit like sex. If you make one mistake, you support it for a lifetime”
71. Versions 1. Break all the things 2. Acquire users 3. Be careful 4. Watch another talk