diff --git a/README.md b/README.md index 68f734a6..0ac37213 100644 --- a/README.md +++ b/README.md @@ -17,27 +17,6 @@ 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 @@ -735,3 +714,24 @@ end ``` The caching interface uses `Rails.cache` under the hood. + +# Design and Implementation Guidelines + +## 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.