github.com/billybanfield/evergreen@v0.0.0-20170525200750-eeee692790f7/apiv3/model/doc.go (about)

     1  /*
     2  	Adding Models
     3  
     4  	Each model is kept in the model package of the REST v2 API in its own file.
     5  	To create a new model, define a struct containing all of the fields that it will return
     6  	and implement its two main interface methods BuildFromService and ToService.
     7  	Be sure to include struct tags to the define the names the fields will have when
     8  	serialized to JSON.
     9  
    10  	Guidlines for Creating Models
    11  
    12  	Include as much data as a user is likely to want when inspecting this resource.
    13  	This is likely to be more information than seems directly needed, but there is
    14  	little penalty to its inclusion.
    15  
    16  	Use APIString instead of Golang's string type. APIString serializes empty strings
    17  	as JSON null instead of Go's zero type of '""'.
    18  
    19  	Use APITime instead of go's time type. APITime is a type that wraps Go's time.Time
    20  	and automatically and correctly serializes it to ISO-8601 UTC time.
    21  
    22  	Return an error when type casting fails.
    23  
    24  	Model Methods
    25  
    26  	The Model type is an interface with two methods.
    27  
    28  					BuildFromService(in interface{}) error
    29  
    30  	BuildFromService fetches all needed data from the passed in object and sets them
    31  	on the model. BuildFromService may sometimes be called multiple times with different
    32  	types that all contain data to build up the model object. In this case, a type switch
    33  	is likely necessary to determine what has been passed in.
    34  
    35  					ToService()(interface{}, error)
    36  
    37  	ToService creates an as-complete-as-possible version of the service layer's version
    38  	of this model. For example, if this is is a REST v2 Task model, the ToService method
    39  	creates a service layer Task and sets all of the fields it is able to and returns it.
    40  */
    41  package model