Building an API in Go using Copilot and Code Gen

Jose Aranguren, jarangutan

whoami

Hi I'm Jose :-)

I like:

• Gardening
• Sourdough
• My dog --->
• Reading documentation
• Concerts

The team

• Yasmine Abdrabo
• William Pennebaker
• Fabiana Fernandez Licon
• Yohan Santos

We are here to help! Raise your hand if you get stuck!

What are the prerequisites?

• Go 1.24+ (https://go.dev/doc/install)
• git (https://git-scm.com/downloads)
• and your favorite IDE

That's it! You can build a lot with just Go

What we're going to do together

• Use OpenAI to build us an OpenAPI spec
• Use Code Generation with our spec to build us an API
• Learn some Go to code up API request handlers
• Build us a database
• Run our API

You'll be coding so get your IDE open!

Did you misspell OpenAI?

No!

OpenAPI (also called swagger) is a formal standard for describing HTTP APIs

Example

openapi: 3.0.4
info:
  title: Sample API
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
  version: 0.1.9
servers:
  - url: http://api.example.com/v1
paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in CommonMark or HTML.
      operationId: getUsers
      responses:
        "200": # status code
          description: A JSON array of user names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

Why make an OpenAPI spec?

• Explains to users what your API does and what it takes/returns
• Unblocks your teammates by having them build clients/mocks off the spec
• Unlocks the use of codegen tools to adhere to the spec
• Lets you design and iterate over the spec faster than writing code

Hold on! What even is an API?

[Application Programming Interface or APIs] act as bridges between different pieces of software, enabling them to communicate, share data, and work together.

While we're at it, what is Go?

Go is a programming language developed by Google that is simple, built for concurrency, and with a strong standard library

package main

import "fmt"

func main() {
    fmt.Println("hello world")
}

But I don't know Go :-(

That's OK! While we are coding, I will be referring to entries in

https://gobyexample.com/

That way, you get something you can go back to when learning more later

What are Code Generators?

In computing, code generation denotes software techniques or systems that generate executable code which may then be used independently of the generator system in a runtime environment.

Are we using AI to generate the code?

No :^)

We'll be using oapi-codegen which is a tool that converts OpenAPI specs into idiomatic Go code

Lets get Started :-)

Go to the project repo: qrco.de/shgows

git clone https://github.com/jarangutan/oapi-ai-gen-workshop.git
git checkout base
go mod tidy

Running our API

## On Windows
go run cmd/api/main.go

## On Linux/Mac we can use make like how we use npm run
make run

POST a Duck to our API

curl --request POST \
  --url http://localhost:8080/ducks \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Jake",
  "color": "red",
  "size": "medium"
}'

GET all Ducks from our API

curl --request GET \
  --url http://localhost:8080/ducks

Fancy tools to work with APIs

Editors

• Swagger Editor - https://editor.swagger.io
• pb33f "The Doctor" - https://pb33f.io/doctor
• Scalar Sandbox - https://sandbox.scalar.com

API Client Tools

• Scalar - https://github.com/scalar/scalar
• Insomnia - https://github.com/Kong/insomnia
• Bruno - https://github.com/usebruno/bruno
• Hoppscotch - https://github.com/hoppscotch/hoppscotch
• Postman - https://www.postman.com/
• and more!

We made it :-D

Awesome job!

If you got stuck or couldn't finish, that's OK!

The main branch has all the working code

## To go from base to main
## branch and run the API
git add .
git commit -m "phew!"
git checkout main
go run cmd/api/main.go

What's next?

Checkout the code in the main repo! There are tons of notes explaining extra bits and pieces of the code

There's also a version of this API that uses sqlite as a database with the same server we just built

But I want more

• Read Go's Standard Library
• Read Go's Blog
  • Specially on slices (1, 2) and strings
• Read Effective Go
• Read Learn Go with tests
• Read others Go code on Github

Most importantly

Go build!

Q and A

Thank you o/

Make yourself into a gopher with https://gopherize.me/