Release notes

0.12.1 - June 25 2017

  • apidoc officially renamed to API Builder
  • apidoc clients in the Com::Bryzek namespace have moved to Io. For example, instead of importing com.bryzek.apidoc... now import io.apibuilder...

Feb 28 2016 - June 19 2017

  • Release full Swagger compatibility = upload swagger or generate a swagger file. See apibuilder-swagger-generator
  • Android: implemented imports, fixed enum values, fixed union types. See PR 217
  • Add implicit converter to make scala 2.11 Either monadic See PR 214
  • Add support for default union type discriminator, making it fully compatible to change a type from a model to a union, declaring the original model as default See PR 212
  • Add http4s/circe client generator See PR 200
  • Fix recursive type issue See PR 209
  • Set better defaults for collections See PR 206
  • Union type support for android_clients See PR 201
  • Remove check for 22 fields See PR 199
  • Make generator classes extensible See PR 198
  • Enable recursively defined union types See PR 196
  • Create new session auth header as default authentication method See PR 635
  • Introduce optional 'default' type for unions with a discriminator See PR 630
  • Support example generation of imported union types See PR 629
  • Upgrade io.swagger.swagger-parser See PR 624
  • Import Swagger YAML files See PR 618
  • Implement Login via GitHub See PR 614

0.11.16 - Feb 28 2016

  • Refactor type system to truly treat collections as types. See PR 415
  • Fix bug with error when visiting /attributes/ when not logged. See PR 416

0.11.14 - Feb 26 2016

  • Official JavaScript clients now available (alpha). This release announces the availability of the JavaScript client code generator. Both ES5 and ES6 versions are available. This should be considered alpha but is already being used in production.
  • Clients can now be downloaded as .tar.gz archives in addition to .zip

0.11.12 - Feb 24 2016

  • Ruby client: Fix bug with serialization of enum to query parameter. See PR 73
  • Fix bug in play routes generation for routes w/ enum and default. See PR 74
  • Fix validation error of 'boxed error' by actually validating the application key. See PR 411
  • Let any org member delete an application / version. See PR 412

0.11.10 - Feb 18 2016

  • Go clients now available (alpha). This release announces the availability of a go client code generator. This should be considered alpha but is already being used in production.
  • Attributes now supported: We have added attributes to apidoc - these are globally defined, with values currently set at the organization level. Code generators can declare what attributes they use - and any attribute values are now made available to the code generators as part of the invocation form. Learn more.
  • Base Url Defaults: If your application has provided a baseUrl, that base url is now available as a constant in the generated clients. In the play, ning and ruby clients, we also auto default the base Url when creating an instance of a new Client.
  • Added validation that if a path parameter is declared in a resource operation, that the path specified contains that parameter

0.11.6 - Jan 21 2016

  • Generate for play and ning clients now create a package named 'interfaces' which defines the Client interface as a trait. This makes it possible to mock the entire client interface.
  • With this release, we have introduced a new code generator named 'play_2_4_mock_client' which generated a mock client that can be used as the basis for unit and integration testing. This mock client makes it easy to override just the methods you need to test a particular scenario.
  • Fix bug that for some organizations introduced an error when searching. See Issue 397

0.11.5 - Jan 20 2016

  • Fix bug introduced that was serializing null values. See Issue 396

0.11.2 - Jan 15 2016

  • Fixed bug to generate correct path for resources for imported models
  • For numeric defaults, if a min and/or max is specified, we validate that the default is not outside min or max.
  • Email notifications on version changes are now only sent if there is an actual diff. Also fixed bug that prevented notifcation when version number was incremented.

0.10.0 - Jan 7 2016

There have been numerous point releases over the past few months fixing small bugs. 0.10.0 introduces a major new feature - union type discriminators - which we highlight here.

  • Introduction of optional discriminator field for Union type. This is a major feature addition to the union type that flattens out the JSON serialization and will be especially helpful for working with union types from javascript or JSON directly.

    When specifying a union type, you can now specify an optional name for a type discriminator field which can then be used in serialization / deserialization to identify the type of object. When specified, the union type will serialize into a flat JSON object with the discriminator field injected.

    Note this change is 100% backwards compatiable as the discriminator field is optional. If you add a discriminator field to an existing union types - you will break the wire format.

    See api.json union type docs and Play Union Types for more information and examples.

  • Add support to infer a parameter type when an operation is defined for a resource of type union
  • Fix bug that prevented inferrence of parameter types for imported models
  • Make history link more prominent
  • Ignore dot in named variables in path params (e.g. "/get/:id.csv")
  • Validate that models do not have multiple fields w/ the same name

0.9.32 - Jul 21 2015

  • Introduction of a play 2.4.x code generator. Only minor changes from 2.3.x.
  • apidoc itself is now running play 2.4.2
  • Introduction of a java model code generator. See PR 29. Many thanks to jkenny for this change.

0.9.30 - Jul 15 2015

  • Change in the API when invoking a code generator. Response now includes a list of files (as opposed to source code). Each file contains a recommended file name and the contents of this file. This change was made in anticipation of a java code generator which requires multiple files. See PR 349 and PR 351. Many thanks to jkenny for this change.
  • Fixed bug in swagger input related to arrays. See PR 361. Many thanks to dspeele for this fix.

0.9.29 - Jun 29 2015

  • Better support for swagger input, including resolution of references and mapping of API Urls to resources. See PR 353 and PR 356. Many thanks to dspeele for these contributions.

0.9.25 - Jun 9 2015

  • New feature to move an application, with its entire history, to a new organization.

0.9.12 - May 26 2015

  • Online history of all changes now available. To access, when viewing a service, select the 'History' link from the versions dropdown in the upper right corner. Or visit /history to view changes for all applications that you can view.
  • Search is now available - you will see the search bar in the upper right corner. The current implementation offers basic keyword search across all of the applications that you have access to.

0.9.11 - May 11 2015

  • Notifications on application update now send out a detailed diff of what has changed in a service. An example email:
          Version 0.0.1 has been uploaded for the application Gilt/Referral
          Breaking changes
          enum activation_type value removed: order_placed
          model removed: placed_order
          model removed: placed_order_form
          Other changes
          enum activation_type value added: order_shipped
          model added: shipped_order
          model added: shipped_order_form
    You can enable the notification by selecting the "Subscriptions" link in the navigation bar after selecting your organization and then subscribing to "For applications that I watch, email me when a version is created.".

0.9.5 - Apr 14 2015

  • Added a required, top level node named 'apidoc' to the api.json upload. The initial purpose of this node is to capture the version of the apidoc specification used by that file. See api.json apidoc for details.
  • Add support for explicitly specifying 404 responses - users will now have to explicitly specify 404 for any responses that return 404s. Previously, any GET method that returned a singleton automatically inferred a 404. See PR 320.

0.9.4 - Apr 10 2015

  • New 'default' keyword for response codes - this feature has been added to enhance support of apidoc uploads using the swagger specification. We now support the keyword 'default' when defining the response code. This keyword can be used to specify a default type for all non specified response codes, which is particularly useful for handling errors. See api.json response for details.
  • Changed the names of the wrapper classes used when a union type includes a primitive type. Previously, we would create wrapper classes - e.g. IntWrapper - that would be used for all the union types. With this change, the scala generators create a unique class based on the union name and the primitive name. For example, a union type named "user" that supported "Int&qout; will now result in a class names "UserInt".

0.9.0 - Apr 2 2015

  • Breaking change: scala client code generators have been updated to treat required/default fields differently. The implication of required is now equivalent to saying that a given field must always be present when a model is sent over the wire. Fields with defaults are required fields for which generated code provides a default value.
    • All non-required fields are represented as options in Scala.
    • All non-required fields are represented as nullable in Ruby.
    • Non-required fields in Scala are now serialized using writeNullable so that they are not mapped to null in the JSON representation.
    • Notably, non-required collections now map to Option in Scala and nullable in Ruby. They no longer default to an empty instance of the collection.
    • Default values are parsed and injected as language specific literals client side.
    • It is illegal to specify a default for a non-required field. You will see a validation error when uploading a service to apidoc.
    For more information, see PR 6 and Issue 5.
  • Experimental support for Swagger Json (2.0 only). This feature allows you to define your service using the swagger spec, version 2.0 and import it into apidoc. This in turns means you can use the apidoc code generators to access services described with swagger. There are a few major caveats:
    • Only a subset of features are supported as swagger has a broader feature set. We are prioritizing future work in apidoc to incorporate these features directly.
    • There is a mismatch between APIs in swagger and Resources in apidoc. Right now we are using a simple pattern match on API Urls to determine resources. You will get an error if an API path cannot automatically be mapped to a resource.
    • We have tested swagger integration using the petstore example only (see petstore-with-external-docs.json) and have not yet verified that the clients actually work... so more to come in this area (and if you are interested in helping - please let us know!)
    When uploading a new version of an application, you will see a drop down to select the type of file you are uploading (or leave blank and we will auto detect swagger based on a json document with a top level key named 'swagger').

0.8.27 - Mar 13 2015

  • Support for Avro IDL! This feature allows you to represent your models using Avro IDL specification. You can upload this file and it will be automatically converted to the apidoc service specification. The primary use cases we are exploring here: (1) when you are only defining events (e.g. no resources / operations) and prefer IDL or already have IDL; (2) support for generate nice libraries / models for working with your models where the input data are already in IDL (hopefully the existing clients from apidoc are useful).

    To use this feature, upload an .avdl file instead of a .json file to your application. We will detect that the file is in Avro IDL format and parse appropriately.

  • Much stronger validation on the elements present in the api.json document - e.g. you will see validation errors if you mistype an attribute. See Issue 292
  • Introduced deprecation element on all relevant types. This allows you to mark elements of your API as deprecated with an optional description. See Issue 220
  • Better handling for original uploads, including identifying your uploads by type. This sets the stage to support more input formats (in addition to api.json). After avro IDL is stable, we are going to look at swagger json as an input format.
  • UI now has a link to delete a specific version of a service. See Issue 300
  • Numerous small bug fixes and minor improvements

0.8.14 - Mar 6 2015

This is a big release - a number of significant new features, a few breaking changes to increase the quality of the code generated clients, and a large internal refactoring. The biggest new features are support for union types and imports.

Breaking Changes

  • We have replaced apiToken with auth in the Client signature. Users who were previously passing in an API token will need to update their code to pass in an instance of Authorization.Basic instead. This lays the foundation to have standard support for more authentication methods.
    class Client(apiUrl: String, apiToken: scala.Option[String] = None)
    is now
    class Client(apiUrl: String, auth: scala.Option[io.apibuilder.api.v0.Authorization] = None)
    In order to use a token, create an instance of basic authorization with:
  • The scala code generators generate new package names:
    • We have replaced the code that converts a service name to a package name so that it is more consistent. The main change is that camelcased service names will now split into sub packages (so apidocSpec becomes apidoc.spec). We think this change makes the package names more approachable and consistent.
    • Code generators automatically include the major version number of each service in the package names being generated. The main goal here is to enable future upgradability of a client application or a service - major version numbers should be incremented each time a backwards incompatible change is made. By including the major version number in the package name we simplify a portion of the upgrade path. Note that you can override this behavior by explicitly providing a namespace in the api.json file you upload to apidoc.
    • package io.apibuilderspec
      is now
      package io.apibuilder.spec.v0
  • Ruby code generated now uses the new namespace as part of the module name in ruby. If you prefer to use the original non nested namespace, you can include  namespace  as an attribute in the api.json file you upload.
  • The scala method name geneators may generate new names in some cases. This is primarily a bug fix where in some cases the resource name was duplicated in the path name (e.g. in the play routes code generator). Example: "GET /:org/agenda-items" previously generated a method name "getAgendaItemsByOrg". This version will generate the name "getByOrg" as we do a better job identifying resource names from paths.
  • We renamed the error package to errors to match other package names. We also moved the FailedRequest class into the errors package.
  • The FailedRequest exception is now simpler (no longer wraps the response object). This allows the failed request object to be serialized, cleaning up stack traces that were otherwise visible in logs/console.
  • In the scala clients, for methods with both parameters and a body, we reordered the parameters so that they would be more natural to use. For example, required path parameters will now appear earlier in argument list. Parameters in the function list are now ordered by:
    1. all required query / form parameters first
    2. the body, if present
    3. remaining parameters
          def postByOrgKey(domain: io.apibuilder.api.v0.models.Domain,
            orgKey: String
    is now
          def postByOrgKey(
            orgKey: String,
            domain: io.apibuilder.models.Domain
  • The resources element in the api.json file must now be a Map. Up until this version, we continued to support the original format of the resources element being an array; this release removes this deprecated feature.

Major Features

  • Union types - apidoc provides support for declaring your own union types (sometimes referred to as sum or algebraic types). The basic idea is that you can express that a particular variable is one of a known set of types. As an example, in an ecommerce system, you might want to accept orders from both registered users (people who actually have a username and password with your service) and also from guest users (e.g. people who have never visited your application before). One way to model this is to define two types, Registered User and Guest User, a single union type User that can be either a Registered User or a Guest User, and then to model your order as having a User.

    See Play Union types for more detailed information, with specific examples of how to use union types using the play clients.

  • Nomenclature change - Services have been renamed to Applications. We found that it was becoming difficult to differentiate between an application, each of its versions, and the actual REST API (or service). More precisely: Organizations contain applications. Each application can contain one or more versions (users upload versions to apidoc).
  • We have introduced a new concept of a Service which is a complete description of a REST service as described by apidoc. Users of apidoc upload api.json files that contain a specification of a REST API. apidoc converts the specification into a service description that we now call a "Service". A Service is a full description of the REST API. The schema for a service can be found at apicollective/apibuilder-spec.
  • Code generators have been moved out of the apidoc code repository and into a separate repository ( Combined with the introduction of the service schema, we now have a much simpler interface to create code generators. Code generators are functions that accept an instance of a service and return a string (actual code). For specific information on the API to create a code generator, see apicollective/apibuilder-generator.
  • Services now have a namespace as part of the service specification. When uploading new version of an application, we automatically create a namespace for each major version by following the format:
          [organization namespace].[formatted service name].[major version number]
    The service name is converted to a namespace by converting to lower case, under score separated (converting from camel case automatically), and then splitting on underscore. Thus for the organization namespace io.apibuilder, version 1 of an application named apidoc-spec will result in a namespace of io.apibuilder.spec.v1.
    1. apidoc now supports importing definitions from other services. The namespace is required in order to resolve a reference to a model or enum imported from another service. See notes below on importing.
    2. the namespace continues to be used in code generation, mapping to package names, for example, in scala code generators.
    3. You can provide your own namespace by including a 'namespace' attribute in your api.json file. See api.json format for more information
  • Imports: You can now import schema definitions from other services into your project. In order to import definitions:
    1. Declare your imports your api.json file by providing the full URI to each service.json specification you would like to include. To find the URL for a service from the UI, navigate to a service and then click "service.json" in the nav bar on the left.
    2. To use a type from an imported service, reference that type using the fully qualified name for the type. For example, if the service you are importing has a namespace of "io.apibuilder.spec.v1" and you want to use the type "service", you would declare the type of your field as "io.apibuilder.spec.v1.service"
    The apicollective/apibuilder-generator project uses imports as part of its declaration - the simplest way to get started is to look at the api.json file for that service.
  • This release introduces a client code generator based on the latest ning version (1.9.11). See example ning 1.9 play project.

Other enhancements / changes

  • You can now create and manage API tokens to programmatically access apidoc applications. Visit /tokens/ to manage tokens. There is an experimental CLI that relies on these tokens available at
  • We added JSON error handling in the play client. This means that you will get a much nicer error message if we are unable to parse the document (we use play json validation here and return the error messages to you via the exception).
  • We also provide a much nicer error message when the service returns an HTTP status code that is not defined in the specification (a common mistake). This should make it much easier to identify these errors. The message will be similar to "HTTP xxx: Unupported response code. Expected: 200, 409"
  • You can now edit your organization via the UI to change your organization key or namespace. Use with care as changing the namespace may change the package names in generated code.
  • We renamed the organization "package name" setting as "namespace" and have made it required.
  • Base url is now optional avoiding need to guess the URL during initial development (before service is deployed)

0.7.39 - December 19, 2014

  • Email subscriptions: You can now subscribe to a number of different email alerts including notification when services are created or updated, and as an org admin, whenever somebody requests to join your organization. We also added email verification - combined with organization level domains, today when a new user joins apidoc they will receive an email message to confirm their email. Upon confirming their email, if their email domain matches a domain that you've setup for your organization, that user will automatically become part of your organization.
  • Watch your favorite services: You can now watch your favorite services. There is an email subscription to receive a notification whenever a service that you watch is updated.
  • If you forget your password, there is now a password reset flow available in the UI.

0.7.7 - Nov 19, 2014

  • Ruby client models now have a copy method that can be used to create copies of the instances with changes to specific fields. Example:
          domain = => "")
          puts domain.copy(:name => "").name
    See Issue 212

0.7.4 - Nov 18, 2014

This is a major release with over 150 individual commits! Main changes are support for community contributed generators and a revamp of the internal type system, providing much more consistency in how we parse types as well as support for Maps of any defined type.

Major features

  • Support for map[Any defined type] (beta): This release introduces expanded support for map types. You can now define a type as Map[xxx] where xxx can be a primitive, enum, or model defined in your service. Prior to this release, we only supported maps where the values were strings. Note that in all cases, the keys of the map must be strings to confirm to the JSON specification. This feature takes advantage of the existing JSON parsers in client libraries to serialize to/from maps using the standard serialization - e.g. serialization works as expected, and because we validate the type of the values in the map, we can guarantee that a proper serializer exists.
  • Support for community code generators (alpha): Generators are now implemented as rest services, with a standard interface described in apidoc. Adding a generator requires two steps:
    1. Create a service implementing the apicollective/apibuilder-generator API.
    2. Visit /generators/ and enter the URL of your service.
    Many thanks to gheine for this contribution! See PR 194 and PR 216.

Minor improvements / bug fixes

  • Add support for a JSON 'object' as a primitive datatype. While usage is anticipated to be rare, there are a few common use-cases to be able to send arbitrary json objects. We've added support for the 'object' datatype as a primitive to support these cases. See Issue 215
  • Ruby client models support explicit JSON serialization - each model will now have a to_json method to make explicit how the client expects json to be generated. See Issue 213
  • Ruby client to_hash method now checks for nil, avoiding null pointer errors in some cases - See Issue 214
  • Remove scala.collection.Seq and replace with Seq - See Issue 204
  • Standardize parameter names in ruby client. See Issue 203
  • Enum value names now handle dots correctly, e.g. incidents.create will generate IncidentsCreate constant in the scala clients. See Issue 199
  • Fix bug in scala clients when an operation has multiple 2xx response codes. See Issue 187
  • Add validation for query parameters with models when there is a body present. See Issue 172

0.6.3 - Oct 9, 2014

  • Added bindables to simplify strongly typed enums and dates in play routes file. See Play Routes
  • Revised documentation, including getting started guid. See Introduction to apidoc.

0.5.42 - Oct 1, 2014

  • Improved documentation, especially for new users!
  • Code refactoring in apidoc itself - project is mature enough now that we were able to replace the internal models used to bootstrap apidoc with the apidoc generated models! Thanks gheine. See PR 176
  • Better pluralization using org.atteo.evo-inflector library. Model pluralization can always be explicitly specified in the api.json file, but this change expands the number of cases covered automatically. See
  • Code generation targets are extensible internally. First step towards opening up a simple way for anybody to contribute generators based on the apidoc model. See PR 171
  • Number of smaller bug fixes

0.5.33 - Sep 23, 2014

  • Date Type: New 'date-iso8601' type introduced. In ruby clients, maps to a Date instance. In JVM clients, maps to an org.joda.time.LocalDate instance. See Issue 161
  • Dates now Supported in paths. When specifing an API, instances of type date are now allowed in the HTTP Path. Previously, we restricted this particular type from path parameters as serialization is unclear; Serialization remains the responsibility of the service itself and thus apidoc will just document that the type is a date. See Issue 161
  • UI refactored so that resources are hyperlinked to their underlying model; All models, even if mapped to resources, are now listed in the Models section of the UI of apidoc. See Issue 152
  • When downloading a client for the 'latest' version of a service, the user agent will reflect the actual version downloaded (instead of 'latest')

0.5.29 - Sep 19, 2014

  • Play client: Move Traits out of client so they can be accessed directly. See Issue 158

0.5.27 - Sep 16, 2014

  • Support for clients using Ning HTTP Async library and Play Json: This release introduces support for a new client library based on ning's http async library. The only dependencies you will need are play-ws and com.ning.async-http-client version 1.8.x. See ning 1 8 sample project for an example SBT project setup to use the ning clients.
  • Refactor of play client libraries. Main change was to remove the GET, POST, PUT, etc. methods and replace with a single _executeRequest method that takes the method as its first parameter. We think this is a more readable implementation and more concise in the client. If you previously directly accessed these methods, you will need to update your code to call _executeRequest instead.
  • Operation body now supports Arrays as a type.
  • Organizations now have a visibility setting which controls whether or not the organization shows up in the public directory. Public services can still be accessed by direct URL regardless of the org setting.
  • Removed experimental support for avro schemas (event based use case too different from REST services).

0.5.13 - Aug 30, 2014

  • Support for public services. Each service now has a settings section to allow you to control the visibility of a service. The options are: "Organization" (available only to members of your org) or "Public" (available to anybody). Public services are visible to all users - but still can only be modified by members of your organizaetion. The default for all existing services is unchanged (restricted to organization). When creating new services you can specify the visibility you desire. To change the visibility of a service, click 'Settings' in the left menu bar when viewing the service..
  • Services can now be deleted - when viewing a service, click Settings in left menu then 'Delete this service' if you would like to remove a service.
  • New test harness to be able to download accessible clients from production to ensure they continue to compile across different target platforms.
  • Numerous small bug fixes and improvements

0.5.4 - Aug 18, 2014

  • Headers are now supported in spec and generated clients via a top level 'headers' declaration. This enables the service author to describe what headers the service understands, including setting default values which will be automatically included in all requests made via the generated clients. See PR 131
  • Improved documentation of api.json format - See apiJson

0.5.0 - Aug 14, 2014

  • Simple command line validation of api.json files! To validate a file, you can now use a public REST endpoint:
    curl -XPOST -d @./api.json
  • Organization metadata now part of settings - To access, visit, click on your organization, click on settings, then click on Metadata. Currently we have one setting which is the package name to use for JVM based clients. This allows you to specify explicitly the package name for all generated clients. See Issue 86
  • Expand support for body to include primitive types and enums. See Issue 139
  • Play and ruby clients now use strong types for all parameters of type enum. Previously these were sent as Strings. See Issue 127
  • Add support to play and ruby clients for GET parameters that are lists - parameters are now sent as proper HTTP parameters. For example, a GET method with type "[id]" will now generate HTTP requests like /foo?id=1&id=2&... Note that as Play framework does not have native support for collections in its routes file, these parameters are explicitly excluded from the generated routes file - instead you will see a comment describing the additional parameter. See Issue 139
  • Better JSON validation around requiring JsObjects for things like models, enum, body, etc. See Issue 138 and Issue 134 for examples.
  • Better error messages when explicitly speciying a 404 response w/ a type. See Issue 135.

0.4.71 - Aug 13, 2014

  • Enums are now supported as first class elements in apidoc. This is a breaking change as the prior implementation (using an enum attribute on fields) is no longer supported. You will get a validation error message to help with migration. See apiJson documentation for notes on the new enum support. See PR 131

0.4.68 - Aug 5, 2014

  • Play 2.2 client support (currently alpha). Main differences with Play 2.3 client related to a few package names that changed in play 2.3 and a runtime error if you attempt to use HTTP PATCH (play 2.2 does not support patch natively). If you need to access a service using patch, you can override the PATCH method in the generated client to implement your own PATCH method. See PR 122
  • Bug fixed in encoding of path parameters - thanks Gary! See PR 120
  • Play client: FailedResponse class renamed to FailedRequest as it is actually the request that failed.
  • User agents in client: All generated clients now provide a default user agent to identify the version of apidoc that generated the client as well as the specific org, service, and version of the service description used to generate the client. See PR 116
  • Few bug fixes to make enum values more readable and to enable using the ruby client library both with objects as well as hashes (from json). See Issue 114, Issue 117, and Issue 118

0.4.55 - Jul 28, 2014

  • First class support for organization domains. Makes it possible to list org domains (e.g., for auto association with org when new users register. See PR 102
  • Ruby client: Improved support for date time objects (able to instantiate models with date times using Ruby's Time or DateTime classes, in addition to existing string support. See PR 105
  • Avro: Add support for DataTime. See PR 106

0.4.53 - Jul 22, 2014

  • Introduce support to generate Avro Schemas (thanks kscaldef!). There is a new code generation target avro_schema that generates AVRO JSON from the model definitions.
  • Add support for domains in the API for organizations - this can be used to associate a new user with an organization automatically based on email domain. Currently only available in API - UI is coming in a future release.
  • Add support for metadata in the API for organizations, with the first attribute of package_name that becomes available to code generators that need a fully qualified package name. Currently only available in API - UI is coming in a future release.
  • API route added to GET /organizations/:guid
  • Add 'body' information to online documentation.
  • Expanded unit tests based on scala coverage plugin.

0.4.50 - Jul 17, 2014

  • Introduce 'body' on operations. For operations that support posting data, you can now specify a 'body' for the JSON document instead of explicit parameters. The body parameter takes a single attribute - type - specifying the name of a model. Example:
      "resources": {
        "message": {
          "operations": [
              "method": "POST",
    	  "body": { "type": "message" }
    Bodies and query parameters are now fully supported in the play 2.3 client and the ruby client.
  • Query parameter support for operations. When specifying a body, you can also specify additional query parameters for an operation. The parameters section of operations is now interpreted as being in the body by default, and if a 'body' element is provided, the parameters are expected to be sent as query parameters. If this works out in practice, we will likely formalize parameter location to enable specifying query parameters without specifying a location.
  • Added date time helper for parsing date time query parameters in play framework routes file. Thanks to Gary Coady - see
  • Update ruby client to ensure enums are fully supported.

0.4.47 - Jul 16, 2014

  • Validation added to verify that any path parameters refer to fields that are required (not possible to specify an optional path parameter).
  • Path parameters now must be a string, uuid, or number - previously we accepted any datatype.
  • Responses of type 204 and 304 cannot return a type - must be unit - datatypes do not make sense for these response types.
  • We no longer accept response codes 404 or 5xx in any json specification. We found inconsistencies across different services with these types, making it difficult / impossible to create clean clients that behaved consistently. A 404 will automatically be handled in the play client for all GET requests, returning either None or Nil depending on whether the method returns a single instance or an array.
  • Play 2.3 Client: Few implicits made private / renamed to avoid name conflicts when a user imports json implicits for multiple services.
  • Fixed bug where ruby client was incorrectly dropping path after domain.
  • Ruby client breaking change: Removed authorize method as signature only supported a single user. Preferred method is to instantiate the client direclty:
, :authorization => Xyz::HttpClient::Authorization.basic(username, password=nil))

0.4.43 - Jul 14, 2014

  • Replace 'values' element with 'enum' to be compliant with JSON Schema.

0.4.42 - Jul 14, 2014

  • Validate that if a response explicitly specifies a 404, that its type is Unit. This ensures that we can build friently clients in scala which can turn a 2xx/404 response into an Option which is much nicer to use when building apps with the client.

0.4.41 - Jul 12, 2014

  • Validate that if a response explicitly specifies a 204, that its type is Unit. Previously we accepted api specifications that incorrectly specified a type.
  • Add validation for path parameters - only strings, UUID, and number types are now supported in path parameters which keeps serialization simpler.
  • Major refactoring of the play client. Highlights include:
    • Methods that can return a 404 are now handled as returning an Option. This means you do not need to catch errors to handle 404s, instead matching on the response leading to much nicer client code.
    • Introduced traits for all resource clients and methods to obtain an instance of the resource client. This should make it simple to mock the clients in tests.
    • Nicer internal implementation of a number of helpers (e.g. generating query parameters, path parameters, etc.). Helps improve readability of the client code.
    • Fix bug to fully specify package of DateTime class.

0.4.40 - Jul 9, 2014

  • Introduce support for new datatype map. For the initial release, both the keys and the values of the map must be String which we believe enables most of the necessary use-cases while minimizing complexity. Strings will natively serialize / deserialize from JSON making the generated clients much simpler to use.
          "models": {
    	"event": {
              "fields": [
                { "name": "tags", "type": "map" }

    This allows the user to pass in key/value pairs using a map.

  • Introduce support for enums. Enums are specified by appending an enum element in the definition of the field. For example:
          "models": {
    	"event": {
              "fields": [
                { "name": "source", "type": "string", "enum": ["incident", "plan"] }
    There are a few constraints on enums:
    • The field type must be string
    • The enum values must be valid names - Names must be alphanumeric and must start with a letter. Valid characters are a-z, A-Z, 0-9 and _ characters. Main reason to restrict character space is to enable code generation tools to produce nice enum classes w/ valid symbols for each value.
  • Validation for path parameters - only strings, UUID, and number types are now supported in path parameters which keeps serialization simpler. Previously we were allowing specification of, for examples, dates as path parameters which we do not intend to support.