restapi

README

package restapi

REST API stands for Representational State Transfer and is an architectural pattern for creating web services.

Roy Fielding developed it in 2000 and has led to a growing collection of RESTful web services that follow the REST principles. Now, REST APIs see widespread use by application developers due to how simply it communicates with other machines over complex operations like COBRA, RPC, or Simple Object Access Protocol (SOAP).

REST is a ruleset that defines best practices for sharing data between clients and the server. It’s essentially a design style used when creating HTTP or other APIs that only asks you to use CRUD functions, regardless of the complexity.

REST applications use HTTP methods like GET, POST, DELETE, and PUT. REST emphasizes the scalability of components and the simplicity of interfaces.

While neglecting a portion of your tools may seem counterintuitive, it ultimately forces you to describe complex behaviours in simple terms.

Not all HTTP APIs are REST APIs.

The API needs to meet the following architectural requirements listed below to be considered a REST API.

These constraints combine to create an application with strong boundaries and a clear separation of concerns. The client receives server data when requested. The client manipulates or displays the data. The client notifies the server of any state changes. REST APIs don’t conceal data from the client, only implementations.

Client-server

REST applications have a server that manages application data and state. The server communicates with a client that handles the user interactions. A clear separation of concerns divides the two components.

Stateless

Servers don’t maintain client state; clients manage their application state. The client’s requests to the server contain all the information required to process them.

Cacheable

Being cacheable is one of the architectural constraints of REST. The servers must mark their responses as cacheable or not. Systems and clients can cache responses when convenient to improve performance. They also dispose of non-cacheable information, so no client uses stale data.

per HTTP methods

GET requests should be cachable by default – until an exceptional condition arises. Usually, browsers treat all GET requests as cacheable.

POST requests are not cacheable by default but can be made cacheable if either an Expires header or a Cache-Control header with a directive, to explicitly allows caching to be added to the response.

Responses to PUT and DELETE requests are not cacheable. Please note that HTTP dates are always expressed in GMT, never local time.

Cache-Control Headers

Below given are the main HTTP response headers that we can use to control caching behaviour:

Expires Header

The Expires HTTP header specifies an absolute expiry time for a cached representation. Beyond that time, a cached representation is considered stale and must be re-validated with the origin server. The server can include time up to one year in the future to indicate a never expiring cached representation.

Expires: Fri, 20 May 2016 19:20:49 GMT

Cache-Control Header

The header value comprises one or more comma-separated directives. These directives determine whether a response is cacheable and, if so, by whom and for how long, e.g. max-age directives.

Cache-Control: max-age=3600

Cacheable responses (whether to a GET or a POST request) should also include a validator — either an ETag or a Last-Modified header.

ETag Header

An ETag value is an opaque string token that a server associates with a resource to identify the state of the resource over its lifetime uniquely. If the resource at a given URL changes, the server must generate a new Etag value. A comparison of them can determine whether two representations of a resource are the same.

While requesting a resource, the client sends the ETag in the If-None-Match header field to the server. The server matches the Etag of the requested resource and the value sent in the If-None-Match header. If both values match, the server sends back a 304 Not Modified status without a body, which tells the client that the cached response version is still good to use (fresh).

ETag: "abcd1234567n34jv"

Last-Modified Header

Whereas a response’s Date header indicates when the server generated the response, the Last-Modified header indicates when the server last changed the associated resource.

This header is a validator to determine if the resource is the same as the previously stored one by the client’s cache. Less accurate than an ETag header, it is a fallback mechanism.

The Last-Modified value cannot be greater than the Date value. Note that the Date header is listed in the forbidden header names.

Uniform interface

Uniform interface is REST’s most well-known feature or rule. Fielding says:

The central feature that distinguishes the REST architectural style from other network-based styles is its emphasis on a uniform interface between components.

REST services provide data as resources with a consistent namespace.

Layered system

Components in the system cannot see beyond their layer. This confined scope allows you to add load-balancers easily and proxies to improve authentication security or performance.

Documentation

Index

• Variables
• func ErrorMapping[Extensions any](ctx context.Context, err error, dto *rfc7807.DTO[Extensions])
• func Mount(multiplexer multiplexer, pattern string, handler http.Handler)
• func MountPoint(mountPoint Path, next http.Handler) http.Handler
• type ErrorHandler
• type Handler
  • func (h Handler[Entity, ID, DTO]) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Mapping
• type Path
• type Router
  • func NewRouter(configure ...func(*Router)) *Router
  • func (router *Router) Mount(path Path, handler http.Handler)
  • func (router *Router) MountRoutes(routes Routes)
  • func (router *Router) ServeHTTP(responseWriter http.ResponseWriter, request *http.Request)
• type Routes

Examples

• Handler
• Routes

Variables

var DefaultBodyReadLimit int64 = 256 * 1024 * 1024

var ErrEntityAlreadyExist = errorutil.UserError{
	ID:      "entity-already-exists",
	Message: "The entity could not be created as it already exists.",
}

var ErrEntityNotFound = errorutil.UserError{
	ID:      "entity-not-found",
	Message: "The requested entity is not found in this resource.",
}

var ErrInternalServerError = errorutil.UserError{
	ID:      "internal-server-error",
	Message: "An unexpected internal server error occurred.",
}

var ErrInvalidRequestBody = errorutil.UserError{
	ID:      "invalid-create-request-body",
	Message: "The request body is invalid.",
}

var ErrMalformedID = errorutil.UserError{
	ID:      "malformed-id-in-path",
	Message: "The received entity id in the path is malformed.",
}

var ErrMethodNotAllowed = errorutil.UserError{
	ID:      "restapi-method-not-allowed",
	Message: "The requested RESTful method is not supported.",
}

var ErrPathNotFound = errorutil.UserError{
	ID:      "path-not-found",
	Message: "The requested path is not found.",
}

var ErrRequestEntityTooLarge = errorutil.UserError{
	ID:      "request-entity-too-large",
	Message: "The request body was larger than the size limit allowed for the server.",
}

Functions

func ErrorMapping

func ErrorMapping[Extensions any](ctx context.Context, err error, dto *rfc7807.DTO[Extensions])

func Mount

func Mount(multiplexer multiplexer, pattern string, handler http.Handler)

Mount will help to register a handler on a request multiplexer in both as the concrete path to the handler and as a prefix match. example:

if pattern -> "/something"
registered as "/something" for exact match
registered as "/something/" for prefix match

func MountPoint

func MountPoint(mountPoint Path, next http.Handler) http.Handler

Types

type ErrorHandler

type ErrorHandler interface {
	HandleError(w http.ResponseWriter, r *http.Request, err error)
}

type Handler

type Handler[Entity, ID, DTO any] struct {
	Resource     crud.ByIDFinder[Entity, ID]
	Mapping      Mapping[Entity, ID, DTO]
	ErrorHandler ErrorHandler
	Router       *Router

	// BodyReadLimit is the max bytes that the handler is willing to read from the request body.
	BodyReadLimit int64
}

Example

m := memory.NewMemory()
fooRepository := memory.NewRepository[Foo, int](m)

h := restapi.Handler[Foo, int, FooDTO]{
	Resource: fooRepository,
	Mapping:  FooMapping{},
}

if err := http.ListenAndServe(":8080", h); err != nil {
	log.Fatalln(err.Error())
}

func (Handler[Entity, ID, DTO]) ServeHTTP

func (h Handler[Entity, ID, DTO]) ServeHTTP(w http.ResponseWriter, r *http.Request)

type Mapping

type Mapping[Entity, ID, DTO any] interface {
	LookupID(Entity) (ID, bool)
	SetID(*Entity, ID)

	EncodeID(ID) (string, error)
	ParseID(string) (ID, error)

	ContextWithID(context.Context, ID) context.Context
	ContextLookupID(ctx context.Context) (ID, bool)

	MapEntity(context.Context, DTO) (Entity, error)
	MapDTO(context.Context, Entity) (DTO, error)
}

type Path

type Path = string

type Router

type Router struct {
	// contains filtered or unexported fields
}

func NewRouter

func NewRouter(configure ...func(*Router)) *Router

func (*Router) Mount

func (router *Router) Mount(path Path, handler http.Handler)

func (*Router) MountRoutes

func (router *Router) MountRoutes(routes Routes)

func (*Router) ServeHTTP

func (router *Router) ServeHTTP(responseWriter http.ResponseWriter, request *http.Request)

type Routes

type Routes map[Path]http.Handler

Example

m := memory.NewMemory()
fooRepository := memory.NewRepository[Foo, int](m)
barRepository := memory.NewRepository[Bar, string](m)

r := restapi.NewRouter(func(router *restapi.Router) {
	router.MountRoutes(restapi.Routes{
		"/v1/api/foos": restapi.Handler[Foo, int, FooDTO]{
			Resource: fooRepository,
			Mapping:  FooMapping{},
			Router: restapi.NewRouter(func(router *restapi.Router) {
				router.MountRoutes(restapi.Routes{
					"/bars": restapi.Handler[Bar, string, BarDTO]{
						Resource: barRepository,
						Mapping:  BarMapping{},
					}})
			}),
		},
	})
})

// Generated endpoints:
//
// Foo Index  - GET       /v1/api/foos
// Foo Create - POST      /v1/api/foos
// Foo Show   - GET       /v1/api/foos/:foo_id
// Foo Update - PATCH/PUT /v1/api/foos/:foo_id
// Foo Delete - DELETE    /v1/api/foos/:foo_id
//
// Bar Index  - GET       /v1/api/foos/:foo_id/bars
// Bar Create - POST      /v1/api/foos/:foo_id/bars
// Bar Show   - GET       /v1/api/foos/:foo_id/bars/:bar_id
// Bar Update - PATCH/PUT /v1/api/foos/:foo_id/bars/:bar_id
// Bar Delete - DELETE    /v1/api/foos/:foo_id/bars/:bar_id
//
if err := http.ListenAndServe(":8080", r); err != nil {
	log.Fatalln(err.Error())
}