07-rest-api.slide

# REST APIs
Course Go
Tags: golang, go

## Outline

- JSON
- HTTP
- REST API
- Go & HTTP
    - Standard library
    - Third party libraries
    - Testing webservers
- OpenAPI
- Templating

## JSON

## JSON

- JavaScript Object Notation
    - Standardized file format
    - Human readable
    - Based on attribute-value pairs
- Nowadays, de-facto standard format for web services communication

## JSON data types

- Number
- String
- Boolean
- Array
- Object
- Null

## JSON

.code assets/lecture-07/json/user.json

## JSON in Go

- JSON serialization and deserialization supported by standard library
    - Called marshalling and unmarshalling in Go
    - Under the `encoding` packages
        - Also supports other common formats:
            - CSV
            - XML
            - Base64 & Base32
            - Binary
            - And a few more...
- Uses reflection

[Go Packages: encoding/json](https://pkg.go.dev/encoding/json)

## JSON in Go (1/2)

.code assets/lecture-07/json/marshalling.go /START OMIT/,/MIDDLE OMIT/

## JSON in Go (2/2)

.play assets/lecture-07/json/marshalling.go /MIDDLE OMIT/,/END OMIT/

## Struct tags

- Encoding formats can be customized using struct tags
    - Discoverable via reflection
        - [StructTag.Get()](https://pkg.go.dev/reflect#StructTag.Get)
    - Also used for ORMs, etc.

[Go Wiki: Well-known struct tags](https://go.dev/wiki/Well-known-struct-tags)

[Matt Holt: json-to-go](https://mholt.github.io/json-to-go/)

## JSON in Go (1/2)

.code assets/lecture-07/json/marshalling-tags.go /START OMIT/,/MIDDLE OMIT/

## JSON in Go (2/2)

.play assets/lecture-07/json/marshalling-tags.go /MIDDLE OMIT/,/END OMIT/

## HTTP

## HTTP

- Hypertext Transfer Protocol
    - Application layer protocol
    - Client-server
- Proposed by [Time Bernars-Lee](https://en.wikipedia.org/wiki/Tim_Berners-Lee) in 1989
    - Foundation of World Wide Web
    - Originally designed to transmit HTML documents
        - Later made extensible via headers

[mdn web docs: HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP)

## HTTP requests

- HTTP version
- HTTP method
    - GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
- URL
- HTTP request headers
    - Key-value pairs
- Optional HTTP body

.code assets/lecture-07/http/request.txt

## HTTP response

- HTTP version
- HTTP status code
- HTTP status message
- HTTP response headers
- Optional HTTP body

.code assets/lecture-07/http/response.txt

## HTTP status codes

- Informational: 1**
- Successful: 2**
- Redirection: 3**
- Client error: 4**
- Server error: 5**

[mdn web docs: HTTP response status codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status)

## HTTP versions

- Purely text versions
- HTTP 0.9
    - The one-line protocol
- HTTP 1.0
    - Used since 1991
    - Standardized in 1996 [[RFC 1945]](https://datatracker.ietf.org/doc/html/rfc1945)
    - Creates new TCP connection per request
- HTTP 1.1
    - Standardized in 1997 [[RFC 2068]](https://datatracker.ietf.org/doc/html/rfc2068)
    - Persistent connections
    - Introduced pipelining 

## HTTP versions

- HTTP 2.0
    - Standardized in 2015 [[RFC 9113]](https://datatracker.ietf.org/doc/html/rfc9113)
    - Aimed to improve performance
    - Messages are embedded into a binary structure
        - Compresses headers
    - Multiplexes messages over a single connection
- HTTP 3.0 
    - Standardized in 2022 [[RFC 9114]](https://datatracker.ietf.org/doc/html/rfc9114)
    - Builds on top of QUIC protocol
        - Runs multiple streams over UDP

[Web Almanac: HTTP](https://almanac.httparchive.org/en/2021/http)

## HTTP 2.0 vs HTTP 3.0 network protocol stack

.image assets/lecture-07/http/http3-http2-protocol-stack.png 480 _

[Robin Marx: Why HTTP/3 is Eating the World](https://pulse.internetsociety.org/blog/why-http-3-is-eating-the-world)

## CORS

- Cross-Origin Resource Sharing
- HTTP-header based mechanism
- Allows servers to specify origins from which browsers can fetch resources

[mdn web docs: HTTP CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)

## Cookies

- Piece of data sent from server to user
- The cookie is stored on the client side
    - Afterwards sent with every request
- Common use cases:
    - Session management
    - Personalization
    - Tracking
    
.code assets/lecture-07/http/cookies.txt

[mdn web docs: HTTP cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies)

## REST API

- REpresentational State Transfer
- Introduced by [Roy Fielding](https://en.wikipedia.org/wiki/Roy_Fielding) in 2000
- Set of architectural constaints
    - Uniform interface
    - Defines a set of resources
    - Stateless communication
    - Client-server architecture
    - Layered system
- Reused already existing HTTP 1.1 methods
    - No changes were required

[mdn web docs: REST](https://developer.mozilla.org/en-US/docs/Glossary/REST)

## Go standard library & HTTP

## net package

- Interfaces for network I/O
    - TCP/IP
    - UDP
    - DNS
    - Unix sockets
- Provides low-level primitives
- Most notable:
    - `Dial`/`Listen` functions
    - And the associated `Conn`/`Listener` interfaces

[Go Packages: net](https://pkg.go.dev/net)

## Dial

.play assets/lecture-07/net/dial.go

## Listen

.play assets/lecture-07/net/listen.go /START OMIT/,/END OMIT/

## net/http package

- Provides HTTP client and server implementations

[Go Internals: HTTP request multiplexing in Go](https://akshay-kumar.hashnode.dev/go-internals-http-request-multiplexing-in-go-1)

[Dreams of Code: The standard library now has all you need for routing in Go](https://www.youtube.com/watch?v=H7tbjKFSg58)

## Simple get

.play assets/lecture-07/net/http/get.go /START OMIT/,/END OMIT/

## Client

.play assets/lecture-07/net/http/client.go /START OMIT/,/END OMIT/

## Server with default handler

- Uses global `http.DefaultServerMux` router

.play assets/lecture-07/net/http/server.go /START OMIT/,/END OMIT/

## Server with router

- Explicit router

.play assets/lecture-07/net/http/server-mux.go /START OMIT/,/END OMIT/

## Configuring server

.play assets/lecture-07/net/http/server-config.go /START OMIT/,/END OMIT/

## Path parameters

- Added in Go 1.22
- Accessed via `PathValue` method

.play assets/lecture-07/net/http/path-parameters.go /START OMIT/,/END OMIT/

## Query parameters

- Accessed via `r.URL.Query()`
    - Returns `Values` type: `map[string][]string` underneath

.play assets/lecture-07/net/http/query-parameters.go /START OMIT/,/END OMIT/

## Methods

- Also added in Go 1.22

.play assets/lecture-07/net/http/methods.go /START OMIT/,/END OMIT/

## Middleware

.play assets/lecture-07/net/http/middleware.go /START OMIT/,/END OMIT/

## Third party routers, frameworks & utilities

## negroni

- Middleware-focused library
- Idiomatic approach to web middleware in Go
- Encourages use of `net/http` handlers
- `negroni.Classic()`
    - `negroni.Recovery`: recovery middleware
        - Catches panics and returns 500 status code
    - `negroni.Logger`: logger middleware
    - `negroni.Static`: static file serving middleware
- [Bunch of third party negroni compatible middlewares](https://github.com/urfave/negroni?tab=readme-ov-file#third-party-middleware)

[GitHub: negroni](https://github.com/urfave/negroni)

## negroni

.play assets/lecture-07/negroni/negroni.go

## mux

- One of the oldest routers, if not the oldest
    - Created in 2012
- Part of the [gorilla web toolkit](https://github.com/gorilla)
    - [sessions](https://github.com/gorilla/sessions) for cookie nad session management
    - [websocket](https://github.com/gorilla/websocket) implements the WebSocket protocol
    - [handlers](https://github.com/gorilla/handlers) is a collection of middleware handlers
    - And a few more...
- Lost maintainers and got archived for some time in December 2022
    - [Revived in July 2023](https://gorilla.github.io/blog/2023-07-17-project-status-update/)

[GitHub: mux](https://github.com/gorilla/mux)

## chi

- Lightweight, idiomatic router
- Compatible with `net/http`
    - Any router or middleware can be reused
- Comes with it's own [middleware package](https://pkg.go.dev/github.com/go-chi/chi/v5/middleware)

[GitHub: chi](https://github.com/go-chi/chi)

[Chi documentation](https://go-chi.io/#/README)

## chi

.code assets/lecture-07/chi/chi.go /START OMIT/,/END OMIT/

[Chi documentation: routing patterns](https://go-chi.io/#/pages/routing?id=routing-patterns-amp-url-parameters)

## chi: subrouters

.code assets/lecture-07/chi/subrouters.go /START OMIT/,/END OMIT/

[Chi documentation: subrouters](https://go-chi.io/#/pages/routing?id=sub-routers)

## chi: routing groups

.code assets/lecture-07/chi/routing-groups.go /START OMIT/,/END OMIT/

[Chi documentation: routing groups](https://go-chi.io/#/pages/routing?id=routing-groups)

## fasthttp

- Alternative HTTP implementation
    - Up to 10x faster than [net/http](https://pkg.go.dev/net/http)
    - Optimized for thousands of small to medium sized requests per second with consistent low millisecond response times
- Does not provide `ServeMux`
- Multiple routers build on top of it:
    - [fiber](https://github.com/gofiber/fiber)
    - [atreugo](https://github.com/savsgio/atreugo)
    - [fasthttp-routing](https://github.com/qiangxue/fasthttp-routing)

[GitHub: fasthttp](https://github.com/valyala/fasthttp)

## Fiber

- [Express](https://expressjs.com) inspired web framework
    - Yes, that Javascript framework
- Built on top of `fasthttp`
- Plenty of [middleware](https://docs.gofiber.io/category/-middleware) built-in
- Handlers use custom context: [fiber.Ctx](https://docs.gofiber.io/api/ctx)

[GitHub: fiber](https://github.com/gofiber/fiber)

[Fiber documentation](https://docs.gofiber.io)

*You will like the docs if you like emojis*

## Fiber

.code assets/lecture-07/fiber/fiber.go /START OMIT/,/END OMIT/

[Fiber documentation: Routing](https://docs.gofiber.io/guide/routing)

## Echo

- Web framework
- Nice documentation
    - Also contains a bunch of [cookbooks](https://echo.labstack.com/docs/category/cookbook)
- Plenty of [middleware](https://echo.labstack.com/docs/category/middleware) built-in
- Handlers also use custom context: [echo.Context](https://echo.labstack.com/docs/context)

[GitHub: echo](https://github.com/labstack/echo)

[Echo documentation](https://echo.labstack.com/docs)

## Echo: quick start

.code assets/lecture-07/echo/echo.go /START OMIT/,/END OMIT/

[Echo documentation: Quick Start](https://echo.labstack.com/docs/quick-start#hello-world)

## Echo: binding

.code assets/lecture-07/echo/binding.go /START OMIT/,/END OMIT/

[Echo documentation: Binding](https://echo.labstack.com/docs/binding)

## Gin

- Fully fledged web framework
    - Pretty feature rich, but somewhat bloated
- Features [martini](https://github.com/go-martini/martini)-like API
    - Martini is no longer maintained
- Documentation is based on [unstructures examples](https://gin-gonic.com/docs/examples/)
    - "Meh..."
- Handlers also use custom context: [gin.Context](https://pkg.go.dev/github.com/gin-gonic/gin#Context)
- Most popular and used Go web framework
     - ~75.000 stars on GitHub

[GitHub: gin](https://github.com/gin-gonic/gin)

[Gin Web Framework: documentation](https://gin-gonic.com/docs/)

## Gin: Model binding

.code assets/lecture-07/gin/model-binding.go /START OMIT/,/END OMIT/

[Gin Web Framework documentation: Model binding and validation](https://gin-gonic.com/docs/examples/binding-and-validation/) 

## Gin: URI binding

.code assets/lecture-07/gin/uri-binding.go /START OMIT/,/END OMIT/

[Gin Web Framework documentation: Bind Uri](https://gin-gonic.com/docs/examples/bind-uri/) 

## Gin: Router groups

.code assets/lecture-07/gin/router-groups.go /START OMIT/,/END OMIT/

[Gin Web Framework documentation: Grouping routes](https://gin-gonic.com/docs/examples/grouping-routes/) 

## Honorable mentions

- [Beego](https://github.com/beego/beego)
- [Revel](https://github.com/revel/revel)
- [Buffalo](https://github.com/gobuffalo/buffalo)
- [Atreugo](https://github.com/savsgio/atreugo)
- [Goji](https://github.com/goji/goji)

## So many options!

- What should I use then?
- Sticking to the **`net/http`** standard libary is a viable option since Go 1.22 release
    - Previously, the package was hard to use
        - A lot of boiler plate had to be written (methods, path parameters)
- When you need to squeeze-out extra performance `fasthttp` could be the way
    - **Fiber/Atreugo**
- When writing complex apps where you can leverage the extra features offered by more advanced frameworks, use them
    - **Gin/Echo**
- No matter the choice, you will, most likely, be fine with any of them

[TechEmpower: Web Framework Benchmarks](https://www.techempower.com/benchmarks/#hw=ph&test=fortune&section=data-r22&l=zijocf-cn3)

## Air

- Live-reloading command line utility for Go apps
- Uses `air.toml` for configuration
- Initialize config:

```
$ air init
```

- Running air:

```
$ air

 # Will run ./tmp/main -h
$ air -- -h

 # Will run air with custom config and pass -h argument to the built binary
$ air -c .air.toml -- -h
```

[GitHub: Air](https://github.com/cosmtrek/air)

## Air: config

.code assets/lecture-07/air/config.toml

## Testing web servers

## net/http/httptest

- Utilities for HTTP testing
    - **`NewRequest()`**
        - Returns `*http.Request`
        - Used for setting up the request
    - **`ResponseRecorder`**
        - Implementation of `http.ResponseWriter`
        - Records mutations for later inspection
    - **`Server`**
        - Runs a HTTP server on a system port
        - Suitable for testing clients

[Go Packages: net/http/httptest](https://pkg.go.dev/net/http/httptest#ResponseRecorder)

## httptest recorder

.code assets/lecture-07/net/http/httptest/recorder.go

## httptest server

.code assets/lecture-07/net/http/httptest/server.go /START OMIT/,/END OMIT/

## OpenAPI

## OpenAPI

- Machine-readable specification for describing web service interfaces
    - Previously known as _Swagger Specification_
    - Published in 2011
    - Latest version is 3.1 (2021)
    - Written in YAML or JSON
- Swagger Tools
    - Tooling around OpenAPI
        - [Editor](https://editor.swagger.io), [UI](https://petstore.swagger.io), Codegen, Parser, ...

[OpenAPI Specification](https://swagger.io/specification/)

[OpenAPI.Tools](https://openapi.tools)

## OpenAPI example

.code assets/lecture-07/openapi/example.yaml

[Swagger: Basic Structure](https://swagger.io/docs/specification/basic-structure/)

## Generating OpenAPI

- Multiple libraries:
    - [swag](https://github.com/swaggo/swag)
        - Only supports version 2.0
    - [go-swagger](https://github.com/go-swagger/go-swagger)
        - Again, supports only version 2.0

## swag

- Tool for generating Open API specification from source code
- Relies on annotations
- Ships with it's own CLI
    - Can reformat your annotations
    - Can run you Swagger UI for you
- Multiple middleware plugins for major routers/frameworks
    - [gin](https://github.com/swaggo/gin-swagger)
    - [fiber](https://github.com/swaggo/fiber-swagger)
    - [echo](https://github.com/swaggo/echo-swagger)
    - [net/http](https://github.com/swaggo/http-swagger)

[GitHub: swag](https://github.com/swaggo/swag)

## swag annotations

.code assets/lecture-07/openapi/annotations.go /START OMIT/,/END OMIT/

## OpenAPI code generation

- Code can also be generated from the specification
    - Generally good at generating boilerplate code
- Multiple tools:
    - [oapi-codegen](https://github.com/deepmap/oapi-codegen)
    - [ogen](https://github.com/ogen-go/ogen)

## OpenAPI parsing and processing

- [kin-openapi](https://github.com/getkin/kin-openapi)
    - Handles OpenAPI version 2.0 and 3.0
    - Version 3.1 got [somewhat stuck](https://github.com/getkin/kin-openapi/issues/230)
- [libopenapi](https://github.com/pb33f/libopenapi)
    - Relatively new (2022)
    - Handlers all major versions
        - 2.0/3.0/3.1

## Templating

## Templating

- Rendering documents
    - Dynamic data
- Built-in templating engine
- Two standard library packages:
    - text/template
    - html/template

[Go Packages: text/template](https://pkg.go.dev/text/template)

## Template data

.code assets/lecture-07/template/text/render.go /DATA START OMIT/,/DATA END OMIT/

## Template

- Variables are templated using `{{ ... }}` syntax
- Supports loops, function calls and conditions

.code assets/lecture-07/template/text/user.tmpl 

## Rendering template

- Templates are executed by appling a data structure
- Templates can be referenced by their names after they are parsed
    - Allows nesting

.play assets/lecture-07/template/text/render.go /RENDER START OMIT/,/RENDER END OMIT/

## html/template

- Exposes the same API as `text/template`
- Provides more security
    - Prevents code injection
    - Assumes the template authors are trusted while data is not

[Go Packages: html/template](https://pkg.go.dev/html/template)