Simple JSON API Spec Compatibility in Golang
Go
Latest commit 0206f41 Oct 6, 2016 @derekdowling committed on GitHub Merge pull request #37 from bsdlp/merge_goji_logger
merge derekdowling/goji2-logger
Permalink
Failed to load latest commit information.
Godeps merge derekdowling/goji2-logger Oct 6, 2016
_vendor merge derekdowling/goji2-logger Oct 6, 2016
client set maximum content length to read Jul 19, 2016
goji2-logger merge derekdowling/goji2-logger Oct 6, 2016
jsh-api merge derekdowling/goji2-logger Oct 6, 2016
.gitignore move to vendor directory supported in go1.6 Jun 29, 2016
.travis.yml move to vendor directory supported in go1.6 Jun 29, 2016
LICENSE Initial commit Nov 11, 2015
README.md correct minor url typo in README Jul 20, 2016
document.go Merge pull request #31 from EtixLabs/sg-flexible-links Jun 19, 2016
document_test.go Adding additional test coverage, fixing broken tests Mar 8, 2016
error.go Enhanced Error Handling Mar 3, 2016
error_test.go Adding error list support Jan 5, 2016
jsh.go merge jsh-api into go-json-spec-handler Jun 29, 2016
link.go Use sub-types instead of embedded type Jun 18, 2016
link_test.go New link implementation that can encode to or decode from a string/ob… Jun 18, 2016
list.go Adding additional test coverage, fixing broken tests Mar 8, 2016
list_test.go Adding additional test coverage, fixing broken tests Mar 8, 2016
object.go Adds the `meta` field to the object. May 9, 2016
object_test.go Passing tests again Dec 22, 2015
parser.go set maximum content length to read Jul 19, 2016
parser_test.go Relationship data structures now follow the spec. Feb 11, 2016
relationship.go Relationship data structures now follow the spec. Feb 11, 2016
relationship_test.go Relationship data structures now follow the spec. Feb 11, 2016
response.go More test fixes Dec 22, 2015
response_test.go Getting closer Dec 22, 2015
test_util.go Separated client logic into own-subpackage along with tests Nov 20, 2015

README.md

A Go JSONAPI Specification Handler

GoDoc Travis CI Go Report Card TestCoverage

A (de)serialization handler for writing JSON API Specification compatible software in Go. Works with Ember/Ember-Data too!

Contents

  1. JSH
  2. JSC
  3. JSH-API

jsh - JSON Specification Handler

For streamlined JSONAPI object serialization. Uses govalidator for input validation.

import github.com/derekdowling/go-json-spec-handler

type User struct {
  // valid from github.com/asaskevich/govalidator gives us input validation
  // when object.Unmarshal() is invoked on this type
  Name string `json:"name" valid:"alphanum"`
}

// example http.HandlerFunc for PATCH /users/1
func PatchUser(w http.ResponseWriter, r *http.Request) {

  // performs Specification checks against the request
  object, err := jsh.ParseObject(r)
  if err != nil {
    // jsh returns API friendly errors, that are easy to respond with
    jsh.Send(w, r, err)
    return
  }

  // use object.ID to look up user/do business logic
  user := &User{}

  // unmarshal data into relevant internal types if govalidator passes, otherwise
  // return the pre-formatted HTTP 422 error to signify how the input failed
  err = object.Unmarshal("users", user)
  if err != nil {
    jsh.Send(w, r, err)
    return
  }

  // modify your resource object
  user.Name = "Bob"

  // repackage and send the updated resource as a response
  err = object.Marshal(user)
  if err != nil {
    jsh.Send(w, r, err)
    return
  }

  jsh.Send(w, r, object)
}

Motivation for JSH

JSH was written for tackling the issue of dealing with Ember-Data within a pre-existing API server. In sticking with Go's philosophy of modules over frameworks, it is intended to be a drop in serialization layer focusing only on parsing, validating, and sending JSONAPI compatible responses.

Features

Implemented:

- Handles both single object and array based JSON requests and responses
- Input validation with HTTP 422 Status support via [go-validator](https://github.com/go-validator/validator)
- Client request validation with HTTP 406 Status responses
- Links, Relationship, Meta fields
- Prepackaged error responses, easy to use Internal Service Error builder
- Smart responses with correct HTTP Statuses based on Request Method and HTTP Headers
- HTTP Client for GET, POST, DELETE, PATCH

TODO:

- [Reserved character checking](http://jsonapi.org/format/upcoming/#document-member-names-reserved-characters)

Not Implementing:

* These features aren't handled because they are beyond the scope of what
  this module is meant to achieve. See [jshapi](https://github.com/derekdowling/go-json-spec-handler/tree/master/jsh-api)
  for a full-fledged API solution that solves many of these problems.

- Routing
- Sorting
- Pagination
- Filtering
- ORM

Stability

jsh has a mostly stabilized core data document model. At this point in time I am not yet ready to declare v1, but am actively trying to avoid breaking the public API. The areas most likely to receive improvement include relationship, link, and metadata management. At this point in time I can confidentally suggest you use jsh without risking major upgrade incompatibility going forward!

jsc - JSON Specification Client

A HTTP JSONAPI Client for making outbound server requests. Built on top of http.Client and jsh:

import github.com/derekdowling/go-json-spec-handler/client

// GET http://your.api/users/1
document, resp, err := jsc.Fetch("http://your.api/", "users", "1")
object := doc.First()

user := &yourUser{}
err := object.Unmarshal("users", user)

JSH-API

If you're looking for a good place to start with a new API, I've since created jshapi which builds on top of Goji 2 and jsh in order to handle the routing structure that JSON API requires as well as a number of other useful tools for testing and mocking APIs as you develop your own projects. JSHAPI is similar in spirit to this project as it inteniontally focuses on eliminating boilerplate from your projects without trying to solve all of the world's problems.

Examples

There are lots of great examples in the tests themselves that show exactly how jsh works. The godocs as linked above have a number of examples in them as well.