Comparison between Goa v1 vs. v3 about the design DSL

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}")
    })
})