jsonapi-resources.md

jsonapi-resources

https://github.com/cerebris/jsonapi-resources

description

Cerebris Corporation

• open source活動好き
• サービス作っていた
• コンサル業したり

みたいな会社が作ったJSON API 準拠のAPI builder

philosophy

• JSON API specificationでRESTを取り扱いやすくした便利ツールというイメージ
• railsへの組み込みをかなり意識して作られている
  • sample app https://github.com/cerebris/peeps
• resourceという概念で整理されている。
  • この名前はどうなのか、、、 gem名から察するに分かるが、、、
  • model名に _resource suffixを問題を解決する
• controllerに include JSONAPI::ActsAsResourceController と定義することで
  • json api準拠のinterfaceとして動作する
  • resourceが自動で連携されるのでなんかキモい感はある

syntax(DSL)のかきやすさ

• controller -> resource -> (model
  • 実質手をいれるのはcontrollerとresource
  • modelもjson api準拠で使うことを意識した作りを矯正される
  • ただしcontrollerはキモい

# ContactsController
class ContactsController < ApplicationController
  include JSONAPI::ActsAsResourceController

  # Prevent CSRF attacks by raising an exception.
  # For APIs, you may want to use :null_session instead.
  protect_from_forgery with: :null_session
end

# contact resource
class ContactResource < JSONAPI::Resource
  # apiで利用するattribute定義
  attributes :name_first, :name_last, :email, :twitter
  attribute :name_full

  # includesの定義やlink生成のために関連が必要
  has_many :phone_numbers

  def name_full
    "#{name_first} #{name_last}"
  end
end

# contact model
class Contact < ActiveRecord::Base
  # resourceの関連の実態はmodelの関連を通してcallされる。
  has_many :phone_numbers

  # validationはmodelに依存する
  validates :name_first, presence: true
  validates :name_last, presence: true
end

• resourceをserviceとしてもつかえるし、modelのwrapperとしても使える
• apiのためのdecoratorみたいな認識を持った

良い面

• validationがいずれからのアクセスによっても共通化出来る
• resourceをserviceとしてもつかえるし、modelのwrapperとしても使える
  • apiのためのdecoratorみたいな認識を持った
• controllerにActsAsResourceController をincludeすると必要なことが一通り整う
• responseとして返すobject郡のsortやら色々便利メソッドがある

悪い面

• APIに伴うresource設計とmodel設計はしっかり切り離したいが、、、
  • ロジックが定義がmodelやresourceに分散する臭がする
  • 自由度はあるが、この自由度が仇になるようなきがしてならない
  • 基本complexなrequirementになることが往々にしてあるはずなので、カジュアルに使えるようにするより、そこらへん意識してドメインしっかり分けて出来ると良いよね
• APIの受け口とresourceの関連が密過ぎてツライ気がする。
  • json api specification準拠だから良いのか？
• validationがresoruceとmodelで定義できないのもツライ
• post requestがデフォルトでtransactionに包まれる
  • この手のものはservice層にちゃんとやりたくなる
  • ツライ臭がする

ドメインがまとまっていない感を感じる

error handling

• processing errorはcontroller
• ソレ以外はresource, modelの定義に分散
• error messageもjson api specification準拠なのでやりやすそうではある
  • http://jsonapi.org/format/#errors

performance

• ほぼcontrollerのwrapper なのでperformanceは普通にrails使うのとあんまし変わらない。

APIの粒度( modelと同等なresource粒度か、それともまとめるか？)

model同等

versioningのしやすさ

• versioningの概念は無い
• routingとcontrollerでなんとかしろってことかな？

messageのサポート種類(mssagepack, xml, json)

• only json!!!

JSONのschemaの厳しさ( HAL, JSON-schemaに固定されているかどうか）

• JSON API specification準拠

template化の可能性

• templateは特に無い

所感

• 大規模なrails案件や、複雑な要件にはあまり 向いていないと思う
• ただ、ある程度楽をしつつ作れる感もある。
• serializerは力作感ある
  • https://github.com/cerebris/jsonapi-resources#serializer

その他

• JSONを利用するAPI策定の流れ
  • http://docs.spring.io/spring-hateoas/docs/current/reference/html/
  • http://stateless.co/hal_specification.html