2.0 Planning

The key components of RP 2.0 will be:

• Responder based serialization (some formal way to handle wrapping types)
• Error handling should be generalised a bit more (extracted into rocket_pants-core) - Done: rocket_pants-core.
  • The error hash should be configurable. The ability to change the RocketPants part of RocketPants::NotFound is very useful when your running multiple applications/engines that utilize the rocket_pants gem. [proposed by @jsmestad]
• RocketPants::Client extracted from the base gem.
  • I would propose eliminating the client all together in favor of 'sample consumers'. Using something like Faraday or the other thousand API client adapters. [proposed by @jsmestad]
• Cleaner, exhibits-based pattern for integration with will_paginate, kaminari etc.
• Build off rails-api to avoid reinventing the wheel.
• Cleaner seperati_on of http-link tools
• Tools for doing Hypermedia APIs
• Defaults for content-type negotiations and/or missing content-type support (ie: if your missing content-type a block allowing possibly a redirect to some docs.example.com/api/users documentation, but id just leave it at accepting a block). [proposed by @jsmestad]
• Integration with ActiveModel serializer
• Simpler to understand / implement caching
• Set primary api version for all specs (not just per-controller spec)
• Way to check API coverage
• Support for CORS

Key Concerns

• What integration hooks are needed / what level?
  • Routing
  • Controller
  • Action
  • Caching?
• Way to swap in / out components
• Must be as simple as possible, lightweight and easy to test.

Header Based Versioning

Need to allow specifying a versioning approach. One of:

• Path Based (include v1 vs 1)
• Header based, custom mime type
• Header based, custom version

Also, documentation explaining why versioning and the trade offs of each approach.

Versioning middleware?

Basically, each versioning approach is just a bit of rack middleware inserted by RocketPants.

They set env["rocket_pants.request_version"] which is verified / managed in the router.

Setting RocketPants.versioning = :something simply sets the class, and the mapper takes care to switch based on the registry.

This is simpler (since the only bit that needs to know how to extract the version is the rack middleware) and means we can specify the version in tests by adding something to the env as needed.

Example: See this gist

Hypermedia Support

HAL

One possible place to start would be HAL - a relatively straight forward approach, easy to implement and possible to declare it in a pretty straight forward manner. The key part would likely be making it simple and possibly declarative to add HAL links.

The one bit I'm not 100% sure on is the way of setting embedded resources. I'd possibly may that optional (but still use the links setting). Maybe let users choose how they wish to represent their resources?

If we could abstract the process of switching that, it would be altogether relatively straight forward.

Compact Objects

Built in serialization support for compact objects would be a big win - automatically add the self url, mark compact=true and the like.