A presentation at London Gophers in 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
OpenAPI is a standard for creating a very detailed and machine-readable description of your API. Once you have that, the machines can use it to create all sorts of goodness. This session will focus on how generated SDKs can fit into a Developer Experience strategy, or going a step further and curating captivating libraries with accurate, maintainable, generated code at its core. Recommended for anyone working with APIs and interested in improving the Developer Experience.
