Go Reference test golangci-lint

jsonapi

Package jsonapi implements a marshaler/unmarshaler for JSON:API v1.0.

Quickstart

Take a look at the go reference for more examples and detailed usage information.

Marshaling

jsonapi.Marshal

type Article struct {
    ID    string `jsonapi:"primary,articles"`
    Title string `jsonapi:"attribute" json:"title"`
}

a := Article{ID: "1", Title:"Hello World"}

b, err := jsonapi.Marshal(&a)
if err != nil {
    // ...
}

fmt.Println("%s", string(b))
// {
//     "data": [
//         "id": "1",
//         "type": "articles",
//         "attributes": {
//             "title": "Hello World"
//         }
//     ]
// }

Unmarshaling

jsonapi.Unmarshal

body := `{"data":[{"id":"1","type":"articles","attributes":{"title":"Hello World"}}]}`

type Article struct {
    ID    string `jsonapi:"primary,articles"`
    Title string `jsonapi:"attribute" json:"title"`
}

var a Article
if err := jsonapi.Unmarshal([]byte(body), &a); err != nil {
    // ...
}

fmt.Prints("%s, %s", a.ID, a.Title)
// "1", "Hello World"

Reference

The following information is well documented in the go reference. This section is included for a high-level overview of the features available.

Struct Tags

Like encoding/json jsonapi is primarily controlled by the presence of a struct tag jsonapi. The standard json tag is still used for naming and omitempty.

Tag Usage Description Alias
primary jsonapi:"primary,{type}" Defines the identification field. N/A
attribute jsonapi:"attribute" Defines an attribute. attr
relationship jsonapi:"relationship" Defines a relationship. rel
meta jsonapi:"meta" Defines a meta object. N/A

Functional Options

Both jsonapi.Marshal and jsonapi.Unmarshal take functional options.

Option Supports
jsonapi.MarshalOption meta, json:api, includes, document links, sparse fieldsets
jsonapi.UnmarshalOption meta

Non-String Identifiers

Identification MUST be represented as a string regardless of the actual type in Go. To support non-string types for the primary field you can implement optional interfaces.

Context Interface
Marshal fmt.Stringer
Marshal jsonapi.MarshalIdentifier
Unmarshal jsonapi.UnmarshalIdentifier

Links

Links are supported via two interfaces and the Link type. To include links you must implement one or both of the following interfaces.

Type Interface
Resource Object Link Linkable
Resource Object Related Resource Link LinkableRelation

Alternatives

google/jsonapi

  • exposes an API that looks/feels a lot different than encoding/json
  • has quite a few bugs w/ complex types in attributes
  • doesn’t provide easy access to top-level fields like meta
  • allows users to generate invalid JSON:API
  • not actively maintained

manyminds/api2go/jsonapi

  • has required interfaces
  • interfaces for includes/relationships are hard to understand and verbose to implement
  • allows users to generate invalid JSON:API
  • part of a broader api2go framework ecosystem

GitHub

View Github