github.com/seeker-insurance/kit@v0.0.13/jsonapi/doc.go (about)

     1  /*
     2  Package jsonapi provides a serializer and deserializer for jsonapi.org spec payloads.
     3  
     4  You can keep your model structs as is and use struct field tags to indicate to jsonapi
     5  how you want your response built or your request deserialzied. What about my relationships?
     6  jsonapi supports relationships out of the box and will even side load them in your response
     7  into an "included" array--that contains associated objects.
     8  
     9  jsonapi uses StructField tags to annotate the structs fields that you already have and use
    10  in your app and then reads and writes jsonapi.org output based on the instructions you give
    11  the library in your jsonapi tags.
    12  
    13  Example structs using a Blog > Post > Comment structure,
    14  
    15  	type Blog struct {
    16  		ID            int       `jsonapi:"primary,blogs"`
    17  		Title         string    `jsonapi:"attr,title"`
    18  		Posts         []*Post   `jsonapi:"relation,posts"`
    19  		CurrentPost   *Post     `jsonapi:"relation,current_post"`
    20  		CurrentPostID int       `jsonapi:"attr,current_post_id"`
    21  		CreatedAt     time.Time `jsonapi:"attr,created_at"`
    22  		ViewCount     int       `jsonapi:"attr,view_count"`
    23  	}
    24  
    25  	type Post struct {
    26  		ID       int        `jsonapi:"primary,posts"`
    27  		BlogID   int        `jsonapi:"attr,blog_id"`
    28  		Title    string     `jsonapi:"attr,title"`
    29  		Body     string     `jsonapi:"attr,body"`
    30  		Comments []*Comment `jsonapi:"relation,comments"`
    31  	}
    32  
    33  	type Comment struct {
    34  		ID     int    `jsonapi:"primary,comments"`
    35  		PostID int    `jsonapi:"attr,post_id"`
    36  		Body   string `jsonapi:"attr,body"`
    37  	}
    38  
    39  jsonapi Tag Reference
    40  
    41  Value, primary: "primary,<type field output>"
    42  
    43  This indicates that this is the primary key field for this struct type. Tag
    44  value arguments are comma separated.  The first argument must be, "primary", and
    45  the second must be the name that should appear in the "type" field for all data
    46  objects that represent this type of model.
    47  
    48  Value, attr: "attr,<key name in attributes hash>[,<extra arguments>]"
    49  
    50  These fields' values should end up in the "attribute" hash for a record.  The first
    51  argument must be, "attr', and the second should be the name for the key to display in
    52  the the "attributes" hash for that record.
    53  
    54  The following extra arguments are also supported:
    55  
    56  "omitempty": excludes the fields value from the "attribute" hash.
    57  "iso8601": uses the ISO8601 timestamp format when serialising or deserialising the time.Time value.
    58  
    59  Value, relation: "relation,<key name in relationships hash>"
    60  
    61  Relations are struct fields that represent a one-to-one or one-to-many to other structs.
    62  jsonapi will traverse the graph of relationships and marshal or unmarshal records.  The first
    63  argument must be, "relation", and the second should be the name of the relationship, used as
    64  the key in the "relationships" hash for the record.
    65  
    66  Use the methods below to Marshal and Unmarshal jsonapi.org json payloads.
    67  
    68  Visit the readme at https://github.com/google/jsonapi
    69  */
    70  package jsonapi