Create Delightful SDKs with OpenAPI

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