# Upgrading

Instructions to upgrade between major versions of `JSONAPIPlug`.

## Upgrading from 1.x to 2.0

  To upgrade your application to 2.0:

  1. Replace all `use JSONAPIPlug.Resource, ...options...` in your `_json.ex` files with one of:
    - `@derive {JSONAPIPlug.Resource, ...options...}` in the module defining your structs.
    - `require Protocol` and `Protocol.derive(JSONAPIPlug.Resource, MyStruct, ...options...)`
      if you prefer to keep it in the `_json.ex` modules.
    - Provide a manual implementation of `JSONAPIPlug.Resource`. This is discouraged
      because the derivation macro generates functions for recasing and options that are tedious to
      implement manually.
  2. Move the `path` option from `JSONAPIPlug.Resource` options to `JSONAPIPlug.Plug` options in your controllers.
  3. `JSONAPIPlug.Resource` attribute options `serialize` and `deserialize` now only support a boolean value.
      Remove all function references passed to `serialize` and `deserialize` and provide an implementation
      of the `JSONAPIPlug.Resource.Attribute` protocol for your resource to do custom serialization/deserialization.
  4. If overridden, replace the `JSONAPIPlug.Resource.links` callback with an implementation of the
     `JSONAPIPlug.Resource.Links` protocol for your resource to add per-resource `JSON:API` links.
  5. If overridden, replace the `JSONAPIPlug.Resource.meta` callback with an implementation of the
    `JSONAPIPlug.Resource.Meta` protocol for your resource to add per-resource `JSON:API` meta.
  6. If you use phonenix, either call `JSONAPIPlug.render/5` in your controllers or add `use MyAppWeb, :json_api`
     to your `_json.ex` modules and call `render/3`. See the README for complete instructions.
  7. If you are sending resource `ids` in `included` for resource create requests, this is now forbidden unless
     the `client_generated_ids` option is configured on your `JSONAPIPlug.API`. You can however use `JSON:API 1.1`
     `lid` in relationships and included resources if you whish to create resources with included resources atomically.
     Please note that this works even though the reported `JSON:API` version is still `1.0`, because the library still
     does not support the full `JSON:API 1.1` specification yet, only `lid` is supported for now.