remote_entity

RemoteEntity

A gem to create entity classes and methods which make http request to remote servers using configuration style. It avoids writing duplicated code that communicates to multiple remote services.

It is something less restricts than her which maps to any http requests (not only for RESTful resources) but comparing to rest-client, this gem is more object oriented. See usage below for details.

Currently it supports oauth2 client_credentials grant type for API authentication.

Supporting Ruby versions

This gem can be used in Ruby >= 2.5.0. However, it might have incompatibilities as this gem was tested with Ruby 3.2.2. Please test thoroughly.

Installation

Install the gem and add to the application's Gemfile by executing:

$ bundle add remote_entity

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install remote_entity

Usage

RemoteEntity.configure(
    name: "User",
    methods: [
        {
            name: "find",
            http_method: "Get",
            url: "https://example.com/users/:id",
            param_mapping: {
                path_params: [:id],
                query_params: [:public]
            },
            authentication: {
                method: "oauth2.client_credentials",
                accepting_instant_token: :authorized_token
            },
            r_turn: true
        },
        {
            name: "create",
            http_method: "Post",
            url: "https://example.com/users",
            param_mapping: {
                body_params: [:name, :age]
            },
            r_turn: false
        }
    ],
    authentications: {
        oauth2: {
            client_credentials: {
                client_id: "client-id",
                client_secret: "client-secret",
                site: "https:/example.com",
                token_url: "/token",
                scope: "users:read users:write",
            }
        }
    }
)

The configuration generated RemoteEntity::User class with find method which can be used by the following example:

RemoteEntity::User.find(id: 1, public: true)

NOTE:

• All entity classes created are under RemoteEntity namespace.
• The classes generated are a typical Ruby class which can be extended, inherited. For example:

class UserService < RemoteEntity::User

end

• The methods generated are class method.
• The method parameter generated from configuration is always key/value pairs (hash)

The method parameters will be transformed into path parameter, query parameter or body parameter of the request by param_mapping configuration. It makes the following GET http request:

curl --location 'https://example.com/users/1?public=true' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>'

Content-Type header as application/json is by default.

Authorization header is generated by oauth2 request using grant type defined in the configuration. The example above uses ouath2 client_credentials grant type. (The gem uses oauth2 gem underdying, so the param structure is pretty the same as oauth2). However, if the method has authentication key which includes accepting_instant_token: :authorized_token, the authentication token request will be bypassed. The authorized_token param value will pass instantly in the request Authorization header. For example:

RemoteEntity::User.find(id: 1, public: true, authorized_token: "authorized-token")

Since the find method is configured to return value (r_turn is set to true), it will return whatever the http response has. For example:

{
    id: 1,
    name: "Jonas",
    age: 22
}

The configuration also creates create method. For example:

RemoteEntity::User.create(name: "John", age: 23)

It will make the following POST http request:

curl --location 'https://example.com/users' \
--header 'Content-Type: application/json' \
--data-raw '
{
"name": "John",
"age": 23
}'

It has no authorization configured, so no Authorization header.

It does not return anything as r_turn is set to false.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/kuroun/remote_entity. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the RemoteEntity project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.