Generating SDKs from OpenAPI Lorna Mitchell, Vonage
A presentation at London Gophers in November 2020 in London, UK by Lorna Jane Mitchell
Generating SDKs from OpenAPI Lorna Mitchell, Vonage
What is OpenAPI? Machine-readable API description (YAML or JSON) • Describe endpoints, with verbs • Parameters, request bodies • Responses The standard formerly known as Swagger @lornajane
Why Describe Your APIs? • Publish API descriptions for developers to use • Generate API reference docs • Import to Postman • Use with mock servers • Generate SDKs and libraries @lornajane
Start with Docs OpenAPI encourages descriptions and examples • Separates content and presentation @lornajane
SDKs for Delightful Developer Experiences @lornajane
Don’t Make Me Think 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
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
We Can Do Better @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 := vonage.CreateAuthFromKeySecret(API_KEY, API_SECRET) verifyClient := vonage.NewVerifyClient(auth) resp, _, _ := verifyClient.Request( PHONE, “GoTest”, vonage.VerifyOpts{}) @lornajane
Auth Helpers Supply auth details: // for basic key/secret auth := vonage.CreateAuthFromKeySecret(“abcd1234”, “VeryS3cr3t”) // for JWT auth privateKey, _ := ioutil.ReadFile(PATH_TO_PRIVATE_KEY_FILE) auth, _ := vonage.CreateAuthFromAppPrivateKey(APP_ID, privateKey) Quickly get a JWT: privateKey, _ := ioutil.ReadFile(“private.key”) g := jwt.NewGenerator(APPLICATION_ID, privateKey) token, _ := g.GenerateToken() @lornajane
Security Helpers SMS API webhooks use signatures from shared secrets if smsClient.checkSig(params, SIG_SECRET, “sha256”) { // data is plausible, do something cool } Make the easy thing also the Right Thing (TM) @lornajane
Builders For example, formatting JSON structures from strongly-typed languages MyNcco := ncco.Ncco{} talk := ncco.TalkAction{ Text: “Go library calling to say hello”, VoiceName: “Nicole” } MyNcco.AddAction(talk) endpoint := []ncco.PhoneEndpoint{Number: “44777000777”} connect := ncco.ConnectAction{Endpoint: endpoint, From: “44777000888”} MyNcco.AddAction(connect) result, _, err := client.CreateCall( vonage.CreateCallOpts{From: from, To: to, Ncco: MyNcco}) @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
SDKs for Delighted Devs OpenAPI lets us focus on the best bits! @lornajane
Thanks! References: • https://github.com/Vonage/vonage-go-sdk • http://spec.openapis.org/ • https://developer.nexmo.com/tools • https://openapi.tools Me: • https://lornajane.net @lornajane
