DEV Community: Taichi Sasaki

Comparison between Goa v1 vs. v3 about the design DSL

Taichi Sasaki — Thu, 24 Oct 2019 10:54:30 +0000

This article compares Goa v1 and v3 design DSL.

v1	v3
`API`	`API`
`APIKeySecurity`	`APIKeySecurity` (`APIKey`) (`APIKeyField`)
~~`AccessCodeFlow`~~ (Obsolete)	-
`Action`	`Method`
~~`ApplicationFlow`~~ (Obsolete)	-
`ArrayOf`	`ArrayOf`
`Attribute`	`Attribute`
`Attributes`	`Attributes`
`BasePath`	`Path`
`BasicAuthSecurity`	`BasicAuthSecurity` (`Password`) (`PasswordField`) (`Username`) (`UsernameField`)
`CONNECT`	`CONNECT`
`CanonicalActionName`	`CanonicalMethod`
`CollectionOf`	`CollectionOf`
`Consumes`	`Consumes`
`Contact`	`Contact`
`ContentType`	`ContentType`
~~`Credentials`~~ (Moved to goa.design/plugins/cors)	-
`DELETE`	`DELETE`
`Default`	`Default`
~~`DefaultMedia`~~ (Obsolete)	-
`Description`	`Description`
`Docs`	`Docs`
`Email`	`Email`
`Enum`	`Enum`
`Example`	`Example` (`Value`)
~~`Expose`~~ (Moved to goa.design/plugins/cors)	-
`Files`	`Files`
`Format`	`Format`
~~`Function`~~ (Obsolete)	-
`GET`	`GET`
`HEAD`	`HEAD`
`HashOf`	`MapOf`
`Header`	`Header`
`Headers`	`Headers`
`Host`	`Host` `Server` `URI` `Variable`
`ImplicitFlow`	`ImplicitFlow`
`JWTSecurity`	`JWTSecurity` (`Token`) (`TokenField`)
`License`	`License`
~~`Link`~~ (Obsolete)	-
~~`Links`~~ (Obsolete)	-
~~`MaxAge`~~ (Moved to goa.design/plugins/cors)	-
`MaxLength`	`MaxLength`
`Maximum`	`Maximum`
`Media`	`Result`
`MediaType`	`ResultType`
~~`Member`~~ (Obsolete)	-
`Metadata`	`Meta`
~~`Methods`~~ (Moved to goa.design/plugins/cors)	-
`MinLength`	`MinLength`
`Minimum`	`Minimum`
`MultipartForm`	`MultipartRequest`
`Name`	`Name`
~~`NoExample`~~ (Obsolete)	-
`NoSecurity`	`NoSecurity`
`OAuth2Security`	`OAuth2Security` (`AccessToken`) (`AccessTokenField`)
`OPTIONS`	`OPTIONS`
~~`OptionalPayload`~~ (Obsolete)	-
~~`Origin`~~ (Moved to goa.design/plugins/cors)	-
`PATCH`	`PATCH`
`POST`	`POST`
`PUT`	`PUT`
~~`Package`~~ (Obsolete)	-
`Param`	`Param`
`Params`	`Params`
`Parent`	`Parent`
`PasswordFlow`	`PasswordFlow`
`Pattern`	`Pattern`
`Payload`	`Payload`
`Produces`	`Produces`
~~`Query`~~ (Obsolete)	-
~~`ReadOnly`~~ (Obsolete)	-
`Reference`	`Reference`
`Required`	`Required`
`Resource`	`Service`
`Response`	`Response`
~~`ResponseTemplate`~~ (Obsolete)	-
~~`Routing`~~ (Obsolete)	-
~~`Scheme`~~ (Obsolete)	-
`Scope`	`Scope`
`Security`	`Security`
`Status`	`Code`
`TRACE`	`TRACE`
`TermsOfService`	`TermsOfService`
`Title`	`Title`
~~`TokenURL`~~ (Obsolete)	-
~~`Trait`~~ (Obsolete)	-
`Type`	`Type`
`TypeName`	`TypeName`
`URL`	`URL`
~~`UseTrait`~~ (Obsolete)	-
`Version`	`Version`
`View`	`View`
-	`AuthorizationCodeFlow`
-	`Body`
-	`ClientCredentialsFlow`
-	`ConvertTo`
-	`CreateFrom`
-	`Elem`
-	`Error`
-	`Extend`
-	`Fault`
-	`Field`
-	`GRPC`
-	`HTTP`
-	`Key`
-	`MapParams`
-	`Message`
-	`Metadata`
-	`Services`
-	`StreamingPayload`
-	`StreamingResult`
-	`Tag`
-	`Temporary`
-	`Timeout`
-	`Trailers`

`BasePath`

Replaced with Path.
Describe in HTTP.

// v1
BasePath("/users")

// v3
HTTP(func() {
    Path("/users")
})

`Consumes`, `Produces`

Describe in HTTP.
Function and Package are obsolete.

// v1
Consumes("application/xml")
Consumes("application/json")
Produces("application/xml")
Produces("application/json")

// v3
HTTP(func() {
    Consumes("application/xml")
    Consumes("application/json")
    Produces("application/xml")
    Produces("application/json")
})

`Format`

The argument type is string in v1. v3 uses expr.ValidationFormat instead.
expr.ValidationFormats are defined in goa.design/goa/expr as const.

`GET`, `HEAD`, `POST`, `PUT`, `DELETE`, `CONNECT`, `OPTIONS`, `TRACE`, `PATCH`

The path parameters are described using colon (:) in v1. v3 uses curly braces ({, }) instead.

// v1
GET("/users/:id")

// v3
GET("/users/{id}")

`HashOf`

Replaced with MapOf.
Describe an optional DSL for the key using Key.
Describe an optional DSL for the value using Elem.

// v1
HashOf(String, Integer,
    func() {
        MinLength(1)
        MaxLength(16)
    },
    func() {
        Minimum(1)
        Maximum(5)
    },
)

// v3
MapOf(String, Int, func() {
    Key(func() {
        MinLength(1)
        MaxLength(16)
    })
    Elem(func () {
        Minimum(1)
        Maximum(5)
    })
})

`Headers`

Request headers

Describe Attribute in Payload, Headers in HTTP.

// v1
Action("show", func() {
    Headers(func() {
        Header("Authorization", String)
    })
})

// v3
Method("show", func() {
    Payload(func() {
        Attribute("Authorization", String)
    })
    HTTP(func() {
        Headers(func() {
            Header("Authorization", String)
        })
    })
})

`Host`, `Scheme`

Host and Scheme (and BasePath) are used in v1. v3 uses Server, Host and URI instead.

// v1
Host("localhost:8080")
Scheme("http")
BasePath("/cellar")

// v3
Server("app", func() {
    Host("development", func() {
        URI("http://localhost:8080/cellar")
    })
})

`NoExample`

Obsolete.
Meta can be used as an alternative.

Meta("swagger:example", "false")

`Params`

Path parameters

Describe Attribute in Payload, Params in HTTP.
Params can be omitted. It is implicitly defined.

// v1
Action("show", func() {
    Params(func() {
        Param("id", Integer)
    })
})

// v3
Method("show", func() {
    Payload(func() {
        Attribute("id", Int)
    })
    HTTP(func() {
        Params(func() {       // Can be omitted
            Param("id", Int)  //
        })                    //
    })
})

Query parameters

Describe Attribute in Payload, Params in HTTP.
Params cannot be ommited.

//v1
Action("list", func() {
    Params(func() {
        Param("name", String)
    })
})

// v3
Method("list", func() {
    Payload(func() {
        Attribute("name", String)
    })
    HTTP(func() {
        Params(func() {            // Cannot be omitted
            Param("name", String)  //
        })                         //
    })
})

`Routing`

Obsolete.
Describe DSLs which have same name as HTTP request methods in HTTP.

// v1
Action("show", func() {
    Routing(
        GET("/:id"),
    )
})

// v3
Method("show", func() {
    HTTP(func() {
        GET("/{id}")
    })
})

Comparison between Goa v1 vs. v3 about the design primitive types

Taichi Sasaki — Fri, 11 Oct 2019 08:02:07 +0000

Goa v3 changed the primitive types used to design from v1. This article compares v1 and v3 primitive types with Swagger data types.

Primitive types of v1

Source: https://godoc.org/gopkg.in/goadesign/goa.v1/design#pkg-constants

const (
    // Boolean is the type for a JSON boolean.
    Boolean = Primitive(BooleanKind)

    // Integer is the type for a JSON number without a fraction or exponent part.
    Integer = Primitive(IntegerKind)

    // Number is the type for any JSON number, including integers.
    Number = Primitive(NumberKind)

    // String is the type for a JSON string.
    String = Primitive(StringKind)

    // DateTime is the type for a JSON string parsed as a Go time.Time
    // DateTime expects an RFC3339 formatted value.
    DateTime = Primitive(DateTimeKind)

    // UUID is the type for a JSON string parsed as a Go uuid.UUID
    // UUID expects an RFC4122 formatted value.
    UUID = Primitive(UUIDKind)

    // Any is the type for an arbitrary JSON value (interface{} in Go).
    Any = Primitive(AnyKind)

    // File is the type for a file. This type can only be used in a multipart definition.
    File = Primitive(FileKind)
)

Primitive types of v3

Source: https://godoc.org/goa.design/goa/expr#pkg-constants

const (
    // Boolean is the type for a JSON boolean.
    Boolean = Primitive(BooleanKind)

    // Int is the type for a signed integer.
    Int = Primitive(IntKind)

    // Int32 is the type for a signed 32-bit integer.
    Int32 = Primitive(Int32Kind)

    // Int64 is the type for a signed 64-bit integer.
    Int64 = Primitive(Int64Kind)

    // UInt is the type for an unsigned integer.
    UInt = Primitive(UIntKind)

    // UInt32 is the type for an unsigned 32-bit integer.
    UInt32 = Primitive(UInt32Kind)

    // UInt64 is the type for an unsigned 64-bit integer.
    UInt64 = Primitive(UInt64Kind)

    // Float32 is the type for a 32-bit floating number.
    Float32 = Primitive(Float32Kind)

    // Float64 is the type for a 64-bit floating number.
    Float64 = Primitive(Float64Kind)

    // String is the type for a JSON string.
    String = Primitive(StringKind)

    // Bytes is the type for binary data.
    Bytes = Primitive(BytesKind)

    // Any is the type for an arbitrary JSON value (interface{} in Go).
    Any = Primitive(AnyKind)
)

Swagger data types

Source: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types

Common Name	`type`	`format`	Comments
integer	`integer`	`int32`	signed 32 bits
long	`integer`	`int64`	signed 64 bits
float	`number`	`float`
double	`number`	`double`
string	`string`
byte	`string`	`byte`	base64 encoded characters
binary	`string`	`binary`	any sequence of octets
boolean	`boolean`
date	`string`	`date`	As defined by `full-date` - RFC3339
dateTime	`string`	`date-time`	As defined by `date-time` - RFC3339
password	`string`	`password`	Used to hint UIs the input needs to be obscured.

Comparison

v3 has more types than v1 to support gRPC. DateTime and UUID are obsoleted but equivalent definitions can be described using the Format DSL. There are many more formats.

v1	v3	Swagger Common Name	Swagger `type`	Swagger `format`
`Boolean`	`Boolean`	boolean	`boolean`
`Integer`	`Int`	long	`integer`	`int64`
	`Int32`	integer	`integer`	`int32`
	`Int64`	long	`integer`	`int64`
	`UInt`	long	`integer`	`int64`
	`UInt32`	integer	`integer`	`int32`
	`UInt64`	long	`integer`	`int64`
`Number`	`Float32`	float	`number`	`float`
	`Float64`	double	`number`	`double`
`String`	`String`	string	`string`
`DateTime`	`String` + `Format(FormatDateTime)`	dateTime	`string`	`date-time`
`UUID`	`String` + `Format(FormatUUID)`		`string`	`uuid`
	`String` + `Format(FormatDate)`	date	`string`	`date`
	`String` + `Format(FormatEmail)`		`string`	`email`
	`String` + `Format(FormatHostname)`		`string`	`hostname`
	`String` + `Format(FormatIPv4)`		`string`	`ipv4`
	`String` + `Format(FormatIPv6)`		`string`	`ipv6`
	`String` + `Format(FormatIP)`		`string`	`ip`
	`String` + `Format(FormatURI)`		`string`	`uri`
	`String` + `Format(FormatMAC)`		`string`	`mac`
	`String` + `Format(FormatCIDR)`		`string`	`cidr`
	`String` + `Format(FormatRegexp)`		`string`	`regexp`
	`String` + `Format(FormatJSON)`		`string`	`json`
	`String` + `Format(FormatRFC1123)`		`string`	`rfc1123`
	`Bytes`	byte	`string`	`byte`
`Any`	`Any`		`any`
`File`			`file`

DEV Community: Taichi Sasaki

Comparison between Goa v1 vs. v3 about the design DSL

BasePath

Consumes, Produces

Format

GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, TRACE, PATCH

HashOf

Headers