如何使用 Rails 5.2 和 Faraday gem 构建复杂的 json 以发布到 web 服务？

Question

My application sends data to a metadata repository through a REST API. I choosed Faraday to handle the HTTP requests. I basically setup some headers, a json dataset, and POST to the webservice. The following code takes place in the skills_controller, and is triggered when the user decides to publish the definition of a variable:

    ### Create the variable for the BusinessArea, get the location header in return
    connection = Faraday.new("https://sis-sms-r.application.opendataquality.ch", :ssl => {:verify => false})
    request_body = {
     definedVariableType: @skill.skill_type.property,
     description: {
       en: @skill.description_translations.where(language: :en).take!,
       de: @skill.description_translations.where(language: :de_OFS).take!,
       fr: @skill.description_translations.where(language: :fr_OFS).take!
      },
     identifier: "Variable TEST 10",
     name: {
       en: @skill.name_translations.where(language: :en).take!,
       de: @skill.name_translations.where(language: :de_OFS).take!,
       fr: @skill.name_translations.where(language: :fr_OFS).take!
      },
     pattern: nil,
     pseudonymized: true,
     validFrom: Time.now,
     validTo: Time.now + 1.year,
     version: "1",
     responsibleDeputy: {
         identifier: @skill.deputy.email,
         name: @skill.deputy.external_directory_id
      },
     responsibleOrgUnit: {
         identifier: @skill.organisation.code,
         name: @skill.organisation.external_reference
      },
     responsiblePerson: {
         identifier: @skill.responsible.email,
         name: @skill.responsible.external_directory_id
      }
    }
  
    puts "--- body"
    puts request_body

    response = connection.post("/api/InformationFields/#{business_area.uuid}/definedVariables") do |req|
      req.body = request_body.to_json
      req.headers['Content-Type'] = 'application/json'
      req.headers['Accept'] =  'application/json'
      req.headers['Authorization'] = "Bearer #{token}"
    end

    puts "--- response"
    puts response.status               # Status 201 => successful request
    puts response.body                 # Message
    puts response.headers["location"]  # uuid of new object

The method then renders an updated partial of the Show view of the skill, with its updated status.

This works fine as long as the request body is quite simple. But I'd like to handle a variable number of translations, and in some cases also send child records to the web service: ie implement loops, nested json objects, and probably partials.

I read about Jbuilder features to create complex json for views. Is there something similar I could use in a controller? Or is there a way to create a json view (and partials) and render it into Faraday' request body? Which would be a good architecture to build this feature? Do you know any article that would describe this?

Thanks a lot for showing me the way.

Answer 1

Start by creating an object that touches your application boundry:

class JSONClient
  attr_reader :connection

  def initialize(base_uri, **opts, &block)
    @connection = Faraday.new(
      base_uri, 
      **opts
    ) do |f|
        f.request :json # encode req bodies as JSON
        f.response :json # decode response bodies as JSON
        yield f if block_given?
    end
  end
end

class BusinessAreaClient < JSONClient
  def initialize(**opts)
    super(
      "https://sis-sms-r.application.opendataquality.ch", 
      ssl: { verify: false},
      **opts
    )
  end

  def defined_variables(skill:, uiid:  token:)
    response = connection.post(
      "/api/InformationFields/#{uuid}/definedVariables"
      SkillSerializer.serialize(skill),
      {
        'Authorization' => "Bearer #{token}"
      }
    )
    if response.success?
      response 
    else
      # handle errors
    end
  end
end

response = BusinessAreaClient.new
                             .defined_variables(
                                 skill: skill,
                                 uuid: business_area.uuid,
                                 token: token
                              )

This gives you object that can be tested in isolation and stubbed out. Its also the only object that should know about the quirks and particularities of the API thus limiting the impact on your application if it should change.

While using a view sounds like a good idea intially you're basically using a very awkward DSL to generate basic data structures like arrays and hashes that map 1-1 to JSON. jBuilder is also very slow.

As a first step to refactoring you could just extract turning a Skill into JSON into its own PORO:

class SkillSerializer < SimpleDelegator
  LANG_MAPPING = {
    en: :en,
    de: :de_OFS,
    fr: :fr_OFS
  }.freeze
  
  def serialize
    {
      definedVariableType: skill_type.property,
      description: translate(description_translations),
      identifier: "Variable TEST 10",
      name: translate(name_translations),
      pattern: nil,
      pseudonymized: true,
      validFrom: Time.now,
      validTo: Time.now + 1.year,
      version: "1",
      responsibleDeputy: {
        identifier: deputy.email,
        name: deputy.external_directory_id
      },
      responsibleOrgUnit: {
        identifier: organisation.code,
        name: organisation.external_reference
      },
      responsiblePerson: {
        identifier: responsible.email,
        name: responsible.external_directory_id
      }
    }
  end

  def self.serialize(object)
    new(object).serialize
  end

  private 
  # should probally be refactored to not cause an excessive amount of queries
  def translate(relation)
    LANG_MAPPING.dup.transform_values do |lang|
      relation.where(language: lang).take!
    end
  end
end

ActiveModel::Serializers is also an option.