TheLazy.Dev
Portfolio GitHub

Blog

go |goadesign

Comparison between Goa v1 vs. v3 about the design DSL

tchssk

Taichi Sasaki

Posted on October 24, 2019

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}")
    })
})
💖 💪 🙅 🚩
tchssk
Taichi Sasaki

Posted on October 24, 2019

Join Our Newsletter. No Spam, Only the good stuff.

Sign up to receive the latest update from our blog.

Related

Comparison between Goa v1 vs. v3 about the design DSL
go Comparison between Goa v1 vs. v3 about the design DSL

October 24, 2019

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

October 11, 2019