Skip to content
This repository has been archived by the owner. It is now read-only.
master
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
bin
 
 
lib
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

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

Original work copyright 2018-2019 Inspire Innovation BV. Continued work copyright 2019 Pablo Crivella.

Read LICENSE for details.

The development of this gem has been sponsored by Inspire Innovation BV (Utrecht, The Netherlands).

About

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

Resources

License

Packages

No packages published
You can’t perform that action at this time.