Client framework for interacting JSON:API Spec compliant APIs in Ruby.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.circleci
bin
lib
spec
.editorconfig
.gitignore
.rspec
.rubocop.yml
.ruby-version
.yardopts
CHANGELOG.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
Gemfile
LICENSE
README.md
Rakefile
jsonapi-record.gemspec

README.md

JSONAPI-Record

Gem Depfu Inline docs CircleCI Maintainability Test Coverage

Client framework for interacting JSON:API Spec compliant APIs in Ruby.

Links:

Requirements

  1. Ruby 2.5.0

Installation

To install, run:

gem install jsonapi-record

Or add the following to your Gemfile:

gem "jsonapi-record"

Usage

Defining resources:

class Base < JSONAPI::Record::Base
  # Sets the base_uri for your API
  base_uri "https://api.example.com"

  # Sets the default headers for your API requests
  default_headers(authorization: "Bearer Token")
end

class User < Base
  # Define JSON:API resource type
  type "users"
end

Defining resource attributes:

class User < Base
  type "users"

  attribute :email, Types::String
  attribute :name, Types::String
  attribute :age, Types::String

  def self.creatable_attribute_names
    super - [:age]
  end

  def self.updatable_attribute_names
    super - [:name]
  end
end

user = User.new(email: "user@example.com", name: "User", age: 28)
user.resource_attributes # => { email: "user@example.com", name: "User", age: 28 }
user.creatable_attributes # => { email: "user@example.com", name: "User" }
user.updatable_attributes # => { email: "user@example.com", age: 28 }

Defining relationships:

class User < JSONAPI::Record::Base
  type "users"

  relationship_to_one :profile, class_name: "Profile"
  relationship_to_many :posts, class_name: "Post"
end

user = User.new(id: "1", profile: Profile.new(id: "1"))
user.profile.class # Profile
user.posts # => []
user.fetch_profile # Performs get request to https://api.example.com/users/1/profile
user.fetch_posts # Performs get request to https://api.example.com/users/1/posts

Querying resources:

user = User.find("1") # Performs get request to https://api.example.com/users/1
user = User.find("1", include: "posts") # Performs get request to https://api.example.com/users/1?include="posts"
user = User.find!("1") # Same as `find` but raises an exception if resource not found
users = User.all # Performs get request to https://api.example.com/users
users = User.all(include: "posts") # Performs get request to https://api.example.com/users?include="posts"

Creating resources:

user = User.new(email: "new@example.com")
created_user = User.create(user) # Performs a post request to https://api.example.com/users
created_user.persisted? # => true
create_user = User.create_with(email: "new@example.com")
create_user.persisted? => true

Updating resources:

user = User.find("1")
user.persisted? # => true
updated_user = User.update(user.new(email: "changed@example.com")) # Performs a patch request to https://api.example.com/users/1

Saving resources:

user = User.find("1")
user.persisted? => # true
updated_user = User.save(user) # Performs a patch request to https://api.example.com/users/1

user = User.new
user.persisted? => # false
created_user = User.save(user) # Performs a post request to https://api.example.com/users
created_user.persisted? => true

Deleting resources:

user = User.find("1")
user.persisted? # => true
deleted_user = User.destroy(user) # Performs a delete request to https://api.example.com/users/1
deleted_user.persisted # => false

Tests

To test, run:

bundle exec rspec spec/

Versioning

Read Semantic Versioning for details. Briefly, it means:

  • Major (X.y.z) - Incremented for any backwards incompatible public API changes.
  • Minor (x.Y.z) - Incremented for new, backwards compatible, public API enhancements/fixes.
  • Patch (x.y.Z) - Incremented for small, backwards compatible, bug fixes.

License

Copyright 2018 Inspire Innovation BV. Read LICENSE for details.