diff --git a/README.md b/README.md index ba83d7fb..3eda4c86 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ [![Build Status](https://api.travis-ci.org/rails-api/active_model_serializers.png)](https://travis-ci.org/rails-api/active_model_serializers) [![Code Climate](https://codeclimate.com/github/rails-api/active_model_serializers.png)](https://codeclimate.com/github/rails-api/active_model_serializers) [![Coverage Status](https://coveralls.io/repos/rails-api/active_model_serializers/badge.png?branch=master)](https://coveralls.io/r/rails-api/active_model_serializers) -# Purpose +# ActiveModel::Serializers + +## Purpose The purpose of `ActiveModel::Serializers` is to provide an object to encapsulate serialization of objects which respond to @@ -14,6 +16,28 @@ content. In short, **serializers replace hash-driven development with object-oriented development.** + +# Design and Implementation + +## Keep it Simple + +ActiveModel::Serializers is capable of producing complex JSON views/large object +trees, and it may be tempting to design in this way so that your client can make +fewer requests to get data and so that related querying can be optimized. +However, keeping things simple in your serializers and controllers may +significantly reduce complexity and maintenance over the long-term development +of your application. Please consider reducing the complexity of the JSON views +you provide via the serializers as you build out your application, so that +controllers/services can be more easily reused without a lot of complexity +later. + +## Performance + +As you develop your controllers or other code that utilizes serializers, try to +avoid n+1 queries by ensuring that data loads in an optimal fashion, e.g. if you +are using ActiveRecord, you might want to use query includes or joins as needed +to make the data available that the serializer(s) need. + # Installing The easiest way to install `ActiveModel::Serializers` is to add it to your @@ -683,24 +707,3 @@ end ``` The caching interface uses `Rails.cache` under the hood. - -# Design and Implementation - -## Keep it Simple - -ActiveModel::Serializers is capable of producing complex JSON views/large object -trees, and it may be tempting to design in this way so that your client can make -fewer requests to get data and so that related querying can be optimized. -However, keeping things simple in your serializers and controllers may -significantly reduce complexity and maintenance over the long-term development -of your application. Please consider reducing the complexity of the JSON views -you provide via the serializers as you build out your application, so that -controllers/services can be more easily reused without a lot of complexity -later. - -## Performance - -As you develop your controllers or other code that utilizes serializers, try to -avoid n+1 queries by ensuring that data loads in an optimal fashion, e.g. if you -are using ActiveRecord, you might want to use query includes or joins as needed -to make the data available that the serializer(s) need.