DEV Community

Taichi Sasaki
Taichi Sasaki

Posted on • Updated on

Comparison between Goa v1 vs. v3 about the design DSL

#go #goadesign

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

Top comments (0)

Read next

piterweb profile image

Golang WebRTC. How to use Pion 🌐Remote Controller

PiterDev -

eminetto profile image

Using test helpers in Go

Elton Minetto -

chigbeef_77 profile image

Level 4, Schmeltool (Coslpore3D Pt:15)

Chig Beef -

omg-a-bear profile image

How I write HTTP services in Go

Björn V -