How to Convert a V2 Endpoint to a V3 Endpoint

This document covers the engineering work for converting a v2 api endpoint to a v3 endpoint. Check out the V3 API Styleguide for more information about the API design of v3.

V2 Architecture

Generally one will find logic pertaining to a particular v2 endpoint in these places:

1. Access Classes (Allowy): app/access
2. Sometimes Actions: app/actions/v2
3. Controllers (RestController::ModelController): app/controllers/runtime
4. Models (Sequel): app/models
5. Sometimes Presenters: app/presenters/v2

V3 Architecture

To v3-ify this same logic, generally we must implement this logic to these places:

1. Actions: app/actions
2. Controllers (Rails ActionController): app/controllers/v3
3. Fetchers: app/fetchers
4. Messages (Rails ActiveModel): app/messages
5. Models (Sequel): app/models
6. Presenters: app/presenters/v3

See a more in-depth discussion of v3 architecture here.

Conversion

Converting a given endpoint is sometimes more of an art than a science, but here is a rough algorithm:

1. Move access logic from the access classes to controllers (collaborating with permission_queryer)
2. Move business logic from the access classes to actions
3. If they exist, keep using the v2 actions or translate them to v3 actions as appropriate
4. Translate the v2 controllers to v3 controllers. Move business logic to actions. Move any complex query logic to fetchers. Move presentation logic to presenters.
5. Keep the models. Move validations that don't require database access to messages. Move business logic to actions. Move presentation logic to presenters. Move queries to fetchers. Because models are shared between v2 and v3, there will often be duplication between models and v3 messages/actions/presenters/fetchers.
6. Move any presentation logic you want to preserve from v2 presenters to v3 presenter.