Upgrading Grape

This document provides guidance on upgrading between major versions of Grape, highlighting breaking changes and necessary code modifications.

Upgrading to >= 3.0.0

Endpoint execution simplified and return deprecated

Executing an endpoint's block has been simplified and calling return in it has been deprecated.

See #2577 for more information.

Old Deprecations Clean Up

  • rack_response has been removed in favor of using error!.
  • Grape::Exceptions::MissingGroupType and Grape::Exceptions::UnsupportedGroupType aliases MissingGroupTypeError andUnsupportedGroupType` have been removed.
  • Grape::Validations::Base has been removed in favor of Grape::Validations::Validators::Base.

See #2573 for more information.

Upgrading to >= 2.4.0

Grape::Middleware::Auth::Base

type is now validated at compile time and will raise a Grape::Exceptions::UnknownAuthStrategy if unknown.

Grape::Middleware::Base

  • Second argument options is now a double splat (**) instead of single splat (*). If you're redefining initialize in your middleware and/or calling super in it, you might have to adapt the signature and the super call. Also, you might have to remove {} if you're pass options as a literal Hash or add ** if you're using a variable.
  • Grape::Middleware::Helpers has been removed. The equivalent method context is now part of Grape::Middleware::Base.

Grape::Http::Headers, Grape::Util::Lazy::Object

Both have been removed. See #2554. Here are the notable changes:

  • Constants like HTTP_ACCEPT have been replaced by their literal value.
  • SUPPORTED_METHODS has been moved to Grape module.
  • HTTP_HEADERS has been moved to Grape::Request and renamed KNOWN_HEADERS. The last has been refreshed with new headers, and it's not lazy anymore.
  • SUPPORTED_METHODS_WITHOUT_OPTIONS and find_supported_method have been removed.

Grape::Middleware::Base

  • Constant TEXT_HTML has been removed in favor of using literal string 'text/html'.
  • rack_request and query_params have been added. Feel free to call these in your middlewares.

Params Builder

  • Passing a class to build_with or Grape.config.param_builder has been deprecated in favor of a symbolized short_name. See SHORTNAME_LOOKUP in lib/grape/params_builder.rb.
  • Including Grape's extensions like Grape::Extensions::Hashie::Mash::ParamBuilder has been deprecated in favor of using build_with at the route level.

Accept Header Negotiation Harmonized

Accept header is now fully interpreted through Rack::Utils.best_q_match which is following RFC2616 14.1. Since Grape 2.1.0, the header versioning strategy was adhering to it, but Grape::Middleware::Formatter never did.

Your API might act differently since it will strictly follow the RFC2616 14.1 when interpreting the Accept header. Here are the differences:

Invalid or missing quality ranking

The following used to yield application/xml and now will yield application/json as the preferred media type:

  • application/json;q=invalid,application/xml;q=0.5
  • application/json,application/xml;q=1.0

For the invalid case, the value invalid was automatically to_f and invalid.to_f equals 0.0. Now, since it doesn't match Rack's regex, its interpreted as non provided and its quality ranking equals 1.0.

For the non provided case, 1.0 was automatically assigned and in a case of multiple best matches, the first was returned based on Ruby's sort_by quality. Now, 1.0 is still assigned and the last is returned in case of multiple best matches. See Rack's implementation of the RFC.

Considering the closest generic when vendor tree

Excluding the header versioning strategy, whenever a media type with the vendor tree leading facet vnd. like application/vnd.api+json was provided, Grape would also consider its closest generic when negotiating. In that case, application/json was added to the negotiation. Now, it will just consider the provided media types without considering any closest generics, and you'll need to register it. You can find the official vendor tree registrations on IANA

Custom Validators

If you now receive an error of 'Grape::Validations.require_validator': unknown validator: your_custom_validation (Grape::Exceptions::UnknownValidator) after upgrading to 2.4.0 then you will need to ensure that you require the your_custom_validation file before your Grape API code is loaded.

See #2533 for more information.

Upgrading to >= 2.3.0

content_type vs api.format inside API

Before 2.3.0, content_type had priority over env['api.format'] when set in an API, which was incorrect. The priority has been flipped and env['api.format'] will be checked first. In addition, the function api_format has been added. Instead of setting env['api.format'] directly, you can call api_format. See #2506 for more information.

Remove Deprecated Methods and Options

  • Deprecated file method has been removed. Use send_file or stream. See #2500 for more information.

  • The except and proc options have been removed from the values validator. Use except_values validator or assign proc directly to values. See #2501 for more information.

  • Passing an options hash and a block to 'desc' deprecation has been removed. Move all hash options to block instead. See #2502 for more information.

Upgrading to >= 2.2.0

Length validator

After Grape 2.2.0, length validator will only take effect for parameters with types that support #length method, will not throw ArgumentError exception.

See #2464 for more information.

For older versions, please refer to the UPGRADING.md file in the repository.