restapisample

README

Sample with REST API

Intention

Just playing with the semantics of the APIs. I've been checking the standard and some resources on the internet:

• https://www.ietf.org/rfc/rfc2616.txt.
• https://restfulapi.net/rest-put-vs-post.
• https://gearheart.io/articles/restful-api-design-best-practices.

Disclaimer

This repo is just for playing and testing, you won't find any test, best practices are applied softly.

Usage

1. Build it.

make

1. Run it (if you don't indicate the port it will run on 8080 by default).

PORT=<YOUR PORT> ./restapisample

1. Curl it!

curl -X GET http://localhost:8080/jobs/01G8XJ74WR5FPT8GAWT44ECEGA
curl -X POST http://localhost:8080/jobs  -d '{"title": "the title, "company": "the company"}'
...

Results

Some thoughts

• My model has not an ID but maybe it should have it. But, it introduces a new challenge, what happens if I want to modify the ID. Should the IDs be modifiable (I believe not!).
• I am using ULIDs as ID. They have interesting properties https://blog.bitsrc.io/ulid-vs-uuid-sortable-random-id-generators-for-javascript-183400ef862c, but they are not human-friendly. Maybe a sort of "sku" should avoid this problem.
• I was trying to use another in-memory key value datastore, but there weren't easy. I love Redis, but it depends on an external software. Maybe there is a better in-memory key value.

Conclusion

Are REST APIs easy? Probably, but sometimes reviewing the concepts is mandatory! Indeed, I was a bit confused about PUT / POST properties before this excercise.

Documentation

Index

• type InMemoryRepo
  • func NewInMemoryRepo() *InMemoryRepo
  • func (repo InMemoryRepo) Create(_ context.Context, job Job) (string, error)
  • func (repo InMemoryRepo) Delete(_ context.Context, id string) error
  • func (repo InMemoryRepo) Get(_ context.Context, id string) (Job, bool, error)
  • func (repo InMemoryRepo) Update(_ context.Context, id string, job Job) error
• type Job
• type Repository
• type Server
  • func NewServer(repository Repository) *Server
  • func (s Server) Start() error

Types

type InMemoryRepo

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

InMemoryRepo implements Repository in a very simple implementation (in memory).

func NewInMemoryRepo

func NewInMemoryRepo() *InMemoryRepo

NewInMemoryRepo creates a new InMemoryRepo.

func (InMemoryRepo) Create

func (repo InMemoryRepo) Create(_ context.Context, job Job) (string, error)

Create creates a new entity in the repository.

func (InMemoryRepo) Delete

func (repo InMemoryRepo) Delete(_ context.Context, id string) error

Delete erases the entity in the repository.

func (InMemoryRepo) Get

func (repo InMemoryRepo) Get(_ context.Context, id string) (Job, bool, error)

Get gets a job from the repository. It will return the Job, a boolean indicating if found or not and an error.

func (InMemoryRepo) Update

func (repo InMemoryRepo) Update(_ context.Context, id string, job Job) error

Update updates an entity in the repository, overwriting if found.

type Job

type Job struct {
	Company     string `json:"company"`
	Title       string `json:"title"`
	Description string `json:"description,omitempty"`
}

Job contains the business model data.

type Repository

type Repository interface {
	Get(ctx context.Context, id string) (Job, bool, error)
	Create(ctx context.Context, job Job) (string, error)
	Update(ctx context.Context, id string, job Job) error
	Delete(ctx context.Context, id string) error
}

Repository implements the behaviour to get, create, update and delete information from a general repository.

type Server

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

Server handles the creation of a gin server.

func NewServer

func NewServer(repository Repository) *Server

NewServer creates a new Server, using a Repository in it.

func (Server) Start

func (s Server) Start() error

Start configures and starts the repository.