# JSON API

## There are mainly two preferred approaches for sending JSON responses:

- Templating engines: explicitly writing the desired response in template files `*.jb` or `*.jbuilder`
- [JB](https://github.com/amatsuda/jb)
- [JBuilder](https://github.com/rails/jbuilder)

- Serialization: separate concerns by using serialization classes (it's just ruby code)
- [FastJSONAPI](https://github.com/Netflix/fast_jsonapi)
- [JSONAPI-serializer](https://github.com/jsonapi-serializer/jsonapi-serializer) (FastJSONAPI fork)
- [ActiveModelSerializers (AMS)](https://github.com/rails-api/active_model_serializers)

## Serialization vs Templating

- Most serialization libraries offer options to transform keys. This is handy especially that Rails (back-end) naming convention prefers camel_case, while Javascript (front-end) prefers snakeCase. Using transform keys, it will always guarantee using proper naming convention in your React application by serializing objects with snakeCase keys, without the need for developers to convert keys manually.

- Serialization libraries will enforce using the [JSON:API specifications](https://jsonapi.org/) which standardize how JSON responses format should look like. This can be easily forgotten or ignored (based on developer preferences) when sending JSON responses with templating engines.

**For example:**
AMS has multiple adapters to choose from:
- Attributes adapter (no root)

  {
    "username": "whatever", 
    "email": "[e-mail]",
    "posts": [
      {
        "id": 1,
        "title": "post 1",
      },
      {
        "id": 2,
        "title": "post 2",
      }
    ]
  }

- JsonApi adapter uses [JSON:API format](https://jsonapi.org/format/)

  { 
    "user": 
      {
        "attributes": 
          {
            "username": "whatever", 
            "email": "[e-mail]",
          },
        "relationships":
            {
              "posts": 
                { 
                  "data" : [
                    {
                      "id": 1,
                      "title": "post 1",
                    },
                    {
                      "id": 2,
                      "title": "post 2",
                    }
                  ]
                }
            }
        } 
  }

Also, JSONAPI-serializer enforces the JSON:API specs by default.

- Serialization libraries allows you to write the least amout of code (in every serializer you specify the attributes that you want to send as json and whether to include its associations) versus templating which requires to write how exactly the response is formatted.

- Serialization libraries are just ruby code, you can use inheritance or composition to construct more complex JSON responses.

- Templating engines are more customizable.
- Templating engines are easier to work with data that doesn't map with the database schema.

## Narrowing down options:

### Comparing performance for Templating Engines:
Results:
[1](https://github.com/amatsuda/jb#benchmarks)
[2](https://gist.github.com/subvertallchris/caaa99727990cfd3e4b3)

### Comparing performance for Serializers
- FastJSONAPI is no longer maintained
- Running the [benchmark](https://github.com/jsonapi-serializer/comparisons) for JSONAPI vs AMS:

## Resources:
- [JBuilder vs AMS](https://stackoverflow.com/questions/26097563/jbuilder-vs-rails-api-active-model-serializers-for-json-handling-in-rails-4)
- [Responding with JSON in Rails](https://www.leighhalliday.com/responding-with-json-in-rails)
- [Which JSON Serializer To Use For A New Rails API?](http://www.carlosramireziii.com/which-json-serializer-to-use-for-a-new-rails-api.html?utm_source=stackoverflow)
- [Benchmarking JBuilder vs AMS](https://web.archive.org/web/20181015174826/https://kirillplatonov.com/2014/11/04/active_model_serializer_vs_jbuilder/)
- [JB vs FastJSON](https://www.reddit.com/r/rails/comments/axuemb/jb_or_fast_jsonapi_when_trying_to_build_a/)
- [Serialization in Rails](http://www.writingsoncode.com/serialization-in-rails)
- [Serialization comparison complete guide](https://buttercms.com/blog/json-serialization-in-rails-a-complete-guide)
- [Comparison](https://qiita.com/sakuraya/items/924ec3c3001938071407)

### JSON:API vs OpenAPI 3 vs JSON