gitlab-org--gitlab-foss/app/serializers
2017-11-02 07:14:35 +01:00
..
concerns Include pagination when rendering expanded hierarchies 2017-10-04 22:49:41 +02:00
analytics_build_entity.rb Re-enable SqlInjection and CommandInjection 2017-08-08 10:50:54 -04:00
analytics_build_serializer.rb
analytics_commit_entity.rb small refactor - removing includes no longer needed 2016-11-17 08:22:59 +01:00
analytics_commit_serializer.rb serialize all the things! 2016-11-17 08:22:58 +01:00
analytics_generic_serializer.rb refactor events facade so it uses separate classes and refactor query stuff 2016-11-17 13:22:27 +01:00
analytics_issue_entity.rb Re-enable SqlInjection and CommandInjection 2017-08-08 10:50:54 -04:00
analytics_issue_serializer.rb refactor events facade so it uses separate classes and refactor query stuff 2016-11-17 13:22:27 +01:00
analytics_merge_request_entity.rb refactor events facade so it uses separate classes and refactor query stuff 2016-11-17 13:22:27 +01:00
analytics_merge_request_serializer.rb refactor events facade so it uses separate classes and refactor query stuff 2016-11-17 13:22:27 +01:00
analytics_stage_entity.rb More updates for translations plus some refactoring. 2017-05-03 21:08:43 -05:00
analytics_stage_serializer.rb added analytics stage serializer and moved some info to the stage classes from the controller 2017-01-17 11:32:54 +01:00
analytics_summary_entity.rb More updates for translations plus some refactoring. 2017-05-03 21:08:43 -05:00
analytics_summary_serializer.rb added new summary serializers and refactor all of the summary stuff into separate logical classes 2017-01-17 11:32:54 +01:00
award_emoji_entity.rb Add full JSON endpoints for issue notes and discussions 2017-07-21 22:35:24 +03:00
base_serializer.rb Rename parameters to params 2017-10-05 13:12:40 +02:00
blob_entity.rb Used new tree and blob entity path helpers 2017-07-20 22:42:36 +01:00
build_action_entity.rb Create and use project path helpers that only need a project, no namespace 2017-07-05 11:11:59 -05:00
build_artifact_entity.rb Create and use project path helpers that only need a project, no namespace 2017-07-05 11:11:59 -05:00
build_details_entity.rb Implemented the new Description Content 2017-09-12 11:19:06 +02:00
build_serializer.rb Rename BuildEntity to JobEntity 2017-06-13 09:53:54 +02:00
cluster_entity.rb Remove status enum from Gcp::Cluster, use state_machine#state 2017-10-04 22:13:10 +02:00
cluster_serializer.rb Introduce serializer for ClusterEntity 2017-10-03 23:21:54 +02:00
cohort_activity_month_entity.rb Use serializer for formatting cohorts data 2017-04-14 15:20:55 +02:00
cohort_entity.rb Use serializer for formatting cohorts data 2017-04-14 15:20:55 +02:00
cohorts_entity.rb Use serializer for formatting cohorts data 2017-04-14 15:20:55 +02:00
cohorts_serializer.rb Use serializer for formatting cohorts data 2017-04-14 15:20:55 +02:00
commit_entity.rb Remove 'Repo' prefix from API entites 2017-10-05 19:48:05 +11:00
container_repositories_serializer.rb Add ContainerTag and ContainerRepository frontend API 2017-09-21 12:21:50 +02:00
container_repository_entity.rb Add ContainerTag and ContainerRepository frontend API 2017-09-21 12:21:50 +02:00
container_tag_entity.rb Fix inability to delete container registry tags 2017-10-18 19:38:12 -07:00
container_tags_serializer.rb Add ContainerTag and ContainerRepository frontend API 2017-09-21 12:21:50 +02:00
deploy_key_entity.rb Pending delete projects should not show in deploy keys 2017-07-25 18:29:33 +01:00
deploy_key_serializer.rb Project deploy keys json end point 2017-03-24 11:53:47 +01:00
deployment_entity.rb Create and use project path helpers that only need a project, no namespace 2017-07-05 11:11:59 -05:00
deployment_serializer.rb use represent_concise instead of separate entity 2017-04-24 22:34:36 +02:00
discussion_entity.rb Remove duplicate attributes from discussion entity and move note.can_edit into note.current_user 2017-07-21 22:35:25 +03:00
discussion_serializer.rb Add full JSON endpoints for issue notes and discussions 2017-07-21 22:35:24 +03:00
entity_date_helper.rb Add translations for elapsed time in words 2017-06-02 08:54:43 -05:00
entity_request.rb
environment_entity.rb Merge branch '29943-environment-folder' into 'security-9-5' 2017-09-07 20:22:16 -04:00
environment_serializer.rb Add a WithPagination concern to reuse across serializers 2017-10-04 22:46:49 +02:00
event_entity.rb Merge request widget redesign 2017-05-09 04:15:34 +00:00
group_child_entity.rb Use polymorphism for common attributes in GroupChildEntity 2017-10-12 11:36:54 +02:00
group_child_serializer.rb Make sure we always return an array of hierarchies 2017-10-13 15:15:45 +02:00
group_entity.rb Created group_icon and group_icon_url 2017-10-04 14:27:09 +02:00
group_serializer.rb Add a WithPagination concern to reuse across serializers 2017-10-04 22:46:49 +02:00
issuable_entity.rb CE port of code changed for epics 2017-11-02 07:14:35 +01:00
issuable_sidebar_entity.rb Load participants async 2017-10-31 16:15:03 +00:00
issue_entity.rb CE port of code changed for epics 2017-11-02 07:14:35 +01:00
issue_serializer.rb Load participants async 2017-10-31 16:15:03 +00:00
issue_sidebar_entity.rb Load participants async 2017-10-31 16:15:03 +00:00
job_entity.rb Re-enable SqlInjection and CommandInjection 2017-08-08 10:50:54 -04:00
job_group_entity.rb Rename BuildEntity to JobEntity 2017-06-13 09:53:54 +02:00
label_entity.rb Fix dashboard labels dropdown 2017-07-07 14:35:16 +01:00
label_serializer.rb Colorize labels in issue search field 2017-05-05 22:47:32 +00:00
merge_request_basic_entity.rb Load participants async 2017-10-31 16:15:03 +00:00
merge_request_basic_serializer.rb Merge request widget redesign 2017-05-09 04:15:34 +00:00
merge_request_create_entity.rb Allow to create new branch and empty WIP merge request from issue page 2017-05-04 08:09:21 +00:00
merge_request_create_serializer.rb Allow to create new branch and empty WIP merge request from issue page 2017-05-04 08:09:21 +00:00
merge_request_entity.rb CE port of code changed for epics 2017-11-02 07:14:35 +01:00
merge_request_serializer.rb Load participants async 2017-10-31 16:15:03 +00:00
note_attachment_entity.rb Add full JSON endpoints for issue notes and discussions 2017-07-21 22:35:24 +03:00
note_entity.rb Fix specs 2017-08-30 10:43:10 +02:00
note_serializer.rb Add full JSON endpoints for issue notes and discussions 2017-07-21 22:35:24 +03:00
note_user_entity.rb Misc tweaks 2017-08-17 19:27:11 +02:00
pipeline_details_entity.rb Merge branch 'master' into feature/gb/persist-pipeline-stages 2017-06-05 12:51:59 +02:00
pipeline_entity.rb Expose failure reason in pipeline error badge 2017-10-05 11:39:54 +02:00
pipeline_serializer.rb Add a WithPagination concern to reuse across serializers 2017-10-04 22:46:49 +02:00
project_entity.rb Enable Layout/TrailingWhitespace cop and auto-correct offenses 2017-08-15 13:44:37 -04:00
README.md Document serializers 2017-05-04 14:28:28 +00:00
request_aware_entity.rb Consistently use monospace font for commit SHAs and branch and tag names 2017-05-12 09:55:25 -05:00
runner_entity.rb Create and use project path helpers that only need a project, no namespace 2017-07-05 11:11:59 -05:00
stage_entity.rb Create and use project path helpers that only need a project, no namespace 2017-07-05 11:11:59 -05:00
status_entity.rb Real time pipeline show action 2017-05-06 16:45:46 +00:00
submodule_entity.rb Added submodule support in multi-file editor 2017-10-20 11:31:57 +01:00
time_trackable_entity.rb CE port of code changed for epics 2017-11-02 07:14:35 +01:00
tree_entity.rb Used new tree and blob entity path helpers 2017-07-20 22:42:36 +01:00
tree_root_entity.rb Many Repo Fixes 2017-08-15 19:53:41 +00:00
tree_serializer.rb Add experimental JSON format for tree controller 2017-05-26 13:51:24 -05:00
user_entity.rb Use UserNoteEntity instead of UserEntity for notes 2017-08-11 18:48:06 +02:00
user_serializer.rb Add data required for note form 2017-07-21 22:35:25 +03:00

Serializers

This is a documentation for classes located in app/serializers directory.

In GitLab, we use grape-entities, accompanied by a serializer, to convert a Ruby object to its JSON representation.

Serializers are typically used in controllers to build a JSON response that is usually consumed by a frontend code.

Why using a serializer is important?

Using serializers, instead of to_json method, has several benefits:

  • it helps to prevent exposure of a sensitive data stored in the database
  • it makes it easier to test what should and should not be exposed
  • it makes it easier to reuse serialization entities that are building blocks
  • it makes it easier to move complexity from controllers to easily testable classes
  • it encourages hiding complexity behind intentions-revealing interfaces
  • it makes it easier to take care about serialization performance concerns
  • it makes it easier to reduce merge conflicts between CE -> EE
  • it makes it easier to benefit from domain driven development techniques

What is a serializer?

A serializer is a class that encapsulates all business rules for building a JSON response using serialization entities.

It is designed to be testable and to support passing additional context from the controller.

What is a serialization entity?

Entities are lightweight structures that allow to represent domain models in a consistent and abstracted way, and reuse them as building blocks to create a payload.

Entities located in app/serializers are usually derived from a Grape::Entity class.

Serialization entities that do require to have a knowledge about specific elements of the request, need to mix RequestAwareEntity in.

A serialization entity usually maps a domain model class into its JSON representation. It rarely happens that a serialization entity exists without a corresponding domain model class. As an example, we have an Issue class and a corresponding IssueSerializer.

Serialization entites are designed to reuse other serialization entities, which is a convenient way to create a multi-level JSON representation of a piece of a domain model you want to serialize.

See documentation for Grape Entites for more details.

How to implement a serializer?

Base implementation

In order to effectively implement a serializer it is necessary to create a new class in app/serializers. See existing serializers as an example.

A new serializer should inherit from a BaseSerializer class. It is necessary to specify which serialization entity will be used to serialize a resource.

class MyResourceSerializer < BaseSerialize
  entity MyResourceEntity
end

The example above shows how a most simple serializer can look like.

Given that the entity MyResourceEntity exists, you can now use MyResourceSerializer in the controller by creating an instance of it, and calling MyResourceSerializer#represent(resource) method.

Note that a resource can be either a single object, an array of objects or an ActiveRecord::Relation object. A serialization entity should be smart enough to accurately represent each of these.

It should not be necessary to use Enumerable#map, and it should be avoided from the performance reasons.

Choosing what gets serialized

It often happens that you might want to use the same serializer in many places, but sometimes the intention is to only expose a small subset of object's attributes in one place, and a different subset in another.

BaseSerializer#represent(resource, opts = {}) method can take an additional hash argument, opts, that defines what is going to be serialized.

BaseSerializer will pass these options to a serialization entity. See how it is documented in the upstream project.

With this approach you can extend the serializer to respond to methods that will create a JSON response according to your needs.

class PipelineSerializer < BaseSerializer
  entity PipelineEntity

  def represent_details(resource)
    represent(resource, only: [:details])
  end

  def represent_status(resource)
    represent(resource, only: [:status])
  end
end

It is possible to use only and except keywords. Both keywords do support nested attributes, like except: [:id, { user: [:id] }].

Passing only and except to the represent method from a controller is possible, but it defies principles of encapsulation and testability, and it is better to avoid it, and to add a specific method to the serializer instead.

Reusing serialization entities from the API

Public API in GitLab is implemented using Grape.

Under the hood it also uses Grape::Entity classes. This means that it is possible to reuse these classes to implement internal serializers.

You can either use such entity directly:

class MyResourceSerializer < BaseSerializer
  entity API::Entities::SomeEntity
end

Or derive a new serialization entity class from it:

class MyEntity < API::Entities::SomeEntity
  include RequestAwareEntity

  unexpose :something
end

It might be a good idea to write specs for entities that do inherit from the API, because when API payloads are changed / extended, it is easy to forget about the impact on the internal API through a serializer that reuses API entities.

It is usually safe to do that, because API entities rarely break backward compatibility, but additional exposure may have a performance impact when API gets extended significantly. Write tests that check if only necessary data is exposed.

How to write tests for a serializer?

Like every other class in the project, creating a serializer warrants writing tests for it.

It is usually a good idea to test each public method in the serializer against a valid payload. BaseSerializer#represent returns a hash, so it is possible to use usual RSpec matchers like include.

Sometimes, when the payload is large, it makes sense to validate it entirely using match_response_schema matcher along with a new fixture that can be stored in spec/fixtures/api/schemas/. This matcher is using a json-schema gem, which is quite flexible, see a documentation for it.

How to use a serializer in a controller?

Once a new serializer is implemented, it is possible to use it in a controller.

Create an instance of the serializer and render the response.

def index
  format.json do
    render json: MyResourceSerializer
      .new(current_user: @current_user)
      .represent_details(@project.resources)
  nd
end

If it is necessary to include additional information in the payload, it is possible to extend what is going to be rendered, the usual way:

def index
  format.json do
    render json: {
      resources: MyResourceSerializer
        .new(current_user: @current_user)
        .represent_details(@project.resources),
      count: @project.resources.count
    }
  nd
end

Note that in these examples an additional context is being passed to the serializer (current_user: @current_user).

How to pass an additional context from the controller?

It is possible to pass an additional context from a controller to a serializer and each serialization entity that is used in the process.

Serialization entities that do require an additional context have RequestAwareEntity concern mixed in. This piece of the code exposes a method called request in every serialization entity that is instantiated during serialization.

An object returned by this method is an instance of EntityRequest, which behaves like an OpenStruct object, with the difference that it will raise an error if an unknown method is called.

In other words, in the previous example, request method will return an instance of EntityRequest that responds to current_user method. It will be available in every serialization entity instantiated by MyResourceSerializer.

EntityRequest is a workaround for #20045 and is meant to be refactored soon. Please avoid passing an additional context that is not required by a serialization entity.

At the moment, the context that is passed to entities most often is current_user and project.

Payload created by a serializer is usually a representation of the backed code, combined with the current request data. Therefore, technically, serializers are presenters that create payload consumed by a frontend code, usually Vue components.

In GitLab, it is possible to use presenters, but BaseSerializer still needs to learn how to use it, see #30898.

It is possible to use presenters when serializer is used to represent only a single object. It is not supported when ActiveRecord::Relation is being serialized.

MyObjectSerializer.new.represent(object.present)

Best practices

  1. Do not invoke a serializer from within a serialization entity.

    If you need to use a serializer from within a serialization entity, it is possible that you are missing a class for an important domain concept.

    Consider creating a new domain class and a corresponding serialization entity for it.

  2. Use only one approach to switch behavior of the serializer.

    It is possible to use a few approaches to switch a behavior of the serializer. Most common are using a Fluent Interface and creating a separate represent_something methods.

    Whatever you choose, it might be better to use only one approach at a time.

  3. Do not forget about creating specs for serialization entities.

    Writing tests for the serializer indeed does cover testing a behavior of serialization entities that the serializer instantiates. However it might be a good idea to write separate tests for entities as well, because these are meant to be reused in different serializers, and a serializer can change a behavior of a serialization entity.

  4. Use ActiveRecord::Relation where possible

    Using an ActiveRecord::Relation might help from the performance perspective.

  5. Be diligent about passing an additional context from the controller.

    Using EntityRequest and RequestAwareEntity is a workaround for the lack of high-level mechanism. It is meant to be refactored, and current implementation is error prone. Imagine the situation that one serialization entity requires request.user attribute, but the second one wants request.current_user. When it happens that these two entities are used in the same serialization request, you might need to pass both parameters to the serializer, which is obviously not a perfect situation.

    When in doubt, pass only current_user and project if these are required.

  6. Keep performance concerns in mind

    Using a serializer incorrectly can have significant impact on the performance.

    Because serializers are technically presenters, it is often necessary to calculate, for example, paths to various controller-actions. Since using URL helpers usually involve passing project and namespace adding includes(project: :namespace) in the serializer, can help to avoid N+1 queries.

    Also, try to avoid using Enumerable#map or other methods that will execute a database query eagerly.

  7. Avoid passing only and except from the controller.

  8. Write tests checking for N+1 queries.

  9. Write controller tests for actions / formats using serializers.

  10. Write tests that check if only necessary data is exposed.

  11. Write tests that check if no sensitive data is exposed.

Future