A (de)serialization handler for writing JSON API Specification compatible software in Go. Works with Ember/Ember-Data too!
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)
}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.
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/jsh-api)
for a full-fledged API solution that solves many of these problems.
- Routing
- Sorting
- Pagination
- Filtering
- ORM
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!
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)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.
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.