A presentation at API Specifications Conference by Lorna Jane Mitchell
Create Delightful SDKs from OpenAPI Lorna Mitchell, Vonage
API Descriptions … What Next? @lornajane
Share and Maintain https://github.com/Nexmo/api-specification/releases This gives developers control. In a good way. @lornajane
Start with Docs OpenAPI encourages descriptions and examples Styles are separate @lornajane
Time to First API Call @lornajane
Generated Code Generated libraries are better than nothing! If there is no library, a code generator gives a developer: • Abstracts away the HTTP handling • Simple validation (probably) • IDE autocomplete for the basic structure @lornajane
Generated Code Reduce cognitive load on your users @lornajane
How to Generate Code This example from https://openapi-generator.tech/ docker run —rm -v ${PWD}:/local openapitools/openapi-generator-cli \ generate \ -i verify.yml \ —package-name verify \ -g go \ -o /local/out/golang/verify @lornajane
Generated Code @lornajane
We Can Do Better @lornajane
SDKs Libraries are a key ingredient of Developer Experience @lornajane
About Generated Code @lornajane
Wrap Sharp Edges For example, the autocomplete example from earlier: ctx := context.withvalue( context.background(), verify.contextapikey, verify.apikey{key: client.apikey} ) result, resp, err := verifyClient.DefaultApi.VerifyRequest( ctx, “json”, client.apiSecret, number, brand, verify.VerifyRequestOpts{}) @lornajane
Wrap Sharp Edges For the user, it’s more like: auth := nexmo.CreateAuthFromKeySecret(API_KEY, API_SECRET) verifyClient := nexmo.NewVerifyClient(auth) resp, _, _ := verifyClient.Request( PHONE, “GoTest”, vonage.VerifyOpts{}) @lornajane
Auth Helpers Add creds to API request, or: auth := nexmo.CreateAuthFromKeySecret(“abcd1234”, “VeryS3cr3t”) Generate a JWT by hand, or: privateKey, _ := ioutil.ReadFile(“private.key”) auth, _ := nexmo.CreateAuthFromAppPrivateKey(“abcdef012345”, privateKey) @lornajane
Provide Escape Routes Do your own JWTs, or customise our helper privateKey, _ := ioutil.ReadFile(PATH_TO_PRIVATE_KEY_FILE) g := jwt.Generator{ ApplicationID: APPLICATION_ID, PrivateKey: privateKey, TTL: time.Minute * time.Duration(90), } g.AddPath(jwt.Path{Path: “/*/users/**”}) token, _ := g.GenerateToken() @lornajane
Security Helpers Webhooks use either signatures from shared secrets, or JWTs $signature = new \Nexmo\Client\Signature( $_GET, SIGNATURE_SECRET, ‘sha256’); // is it valid? Will be true or false $isValid = $signature->check($_GET[‘sig’]); @lornajane
Builders For example, formatting JSON structures from strongly-typed languages TalkAction intro = TalkAction.builder(“Hi! Speak after the beep”) .voiceName(VoiceName.KIMBERLY) .build(); RecordAction record = RecordAction.builder() .beepStart(true) .endOnKey(‘#’) .build() res.type(“application/json”); return new Ncco(intro, record).toJson(); @lornajane
Delightful SDKs Wrappers are the “Delight” in the “Delightful SDK” @lornajane
Go The Extra Mile For added customer delight: • Code examples, for everything • Detailed tutorials, joining up more than one piece of the puzzle For your own delight: • Download stats • Usage stats @lornajane
All APIs Deserve Delightful SDKs OpenAPI lets us focus on the best bits! @lornajane
Thanks! References: • http://spec.openapis.org/ • https://developer.nexmo.com/tools • https://openapi.tools Me: • https://lornajane.net @lornajane
