md-notes-resource

Getting Started with MdNotes

Getting Started

Introduction

API for Markdown Notes app.

Install the Package

Install the gem from the command line:

gem install md-notes-resource -v 2.0

Or add the gem to your Gemfile and run bundle:

gem 'md-notes-resource', '2.0'

For additional gem details, see the RubyGems page for the md-notes-resource gem.

Initialize the API Client

The following parameters are configurable for the API Client:

Parameter	Type	Description
o_auth_client_id	String	OAuth 2 Client ID
o_auth_client_secret	String	OAuth 2 Client Secret
o_auth_username	String	OAuth 2 Resource Owner Username
o_auth_password	String	OAuth 2 Resource Owner Password
timeout	Float	The value to use for connection timeout. Default: 60
max_retries	Integer	The number of times to retry an endpoint call if it fails. Default: 0
retry_interval	Float	Pause in seconds between retries. Default: 1
backoff_factor	Float	The amount to multiply each successive retry's interval amount by in order to provide backoff. Default: 2
retry_statuses	Array	A list of HTTP statuses to retry. Default: [408, 413, 429, 500, 502, 503, 504, 521, 522, 524]
retry_methods	Array	A list of HTTP methods to retry. Default: %i[get put]
o_auth_token	OAuthToken	Object for storing information about the OAuth token

The API client can be initialized as follows:

client = MdNotes::Client.new(
  o_auth_client_id: 'OAuthClientId',
  o_auth_client_secret: 'OAuthClientSecret',
  o_auth_username: 'OAuthUsername',
  o_auth_password: 'OAuthPassword',
)

Authorization

The SDK will attempt to authorize by providing no scopes in case an endpoint requiring authentication is called. You can also authorize the client yourself.

Your application must obtain user authorization before it can execute an endpoint call. The SDK uses OAuth 2.0 Authorization to authorize the client.

The authorize() method will exchange the user's credentials for an access token. The access token is an object containing information for authorizing client requests and refreshing the token itself.

begin
  client.auth.authorize()
rescue OAuthProviderException => ex
  # handle exception
rescue APIException => ex
  # handle exception
end

The client can now make authorized endpoint calls.

Refreshing the token

An access token may expire after sometime. To extend its lifetime, you must refresh the token.

if client.auth.is_token_expired
  begin
    client.auth.refresh_token
  rescue OAuthProviderException => ex
    # handle exception
  end
end

If a token expires, the SDK will attempt to automatically refresh the token before the next endpoint call requiring authentication.

Storing an access token for reuse

It is recommended that you store the access token for reuse.

# store token
save_token_to_database(client.config.o_auth_token)

Creating a client from a stored token

To authorize a client from a stored access token, just set the access token in Configuration along with the other configuration parameters before creating the client:

# load token later...
client.config.o_auth_token = load_token_from_database

# Set other configuration, then instantiate client
client = Client.new

Complete example

require 'md_notes'

include md_notes

# function for storing token to database
def save_token_to_database(token)
  # code to save the token to database
end

# function for loading token from database
def load_token_from_database
  # load token from database and return it (return nil if no token exists)
end

# create a new client
client = MdNotes::Client.new(
  o_auth_client_id: 'OAuthClientId',
  o_auth_client_secret: 'OAuthClientSecret',
  o_auth_username: 'OAuthUsername',
  o_auth_password: 'OAuthPassword',
)

# obtain access token, needed for client to be authorized
previous_token = load_token_from_database
if previous_token
  # restore previous access token
  client.config.o_auth_token = previous_token
else
  # obtain new access token
  begin
    client.auth.authorize()
  rescue OAuthProviderException => ex
    # handle exception
  rescue APIException => ex
    # handle exception
  end
end

# the client is now authorized; you can use client to make endpoint calls
# client will automatically refresh the token when it expires and call the token update callback

Client Class Documentation

MdNotes Client

The gateway for the SDK. This class acts as a factory for the Controllers and also holds the configuration of the SDK.

Controllers

Name	Description
service	Gets ServiceController
user	Gets UserController
o_auth_authorization	Gets OAuthAuthorizationController

API Reference

List of APIs

• Service
• User

Service

Overview

Get instance

An instance of the ServiceController class can be accessed from the API Client.

service_controller = client.service

Get Status

def get_status

Response Type

ServiceStatus

Example Usage

result = service_controller.get_status()

User

Overview

Get instance

An instance of the UserController class can be accessed from the API Client.

user_controller = client.user

Get User

def get_user

Response Type

User

Example Usage

result = user_controller.get_user()

Model Reference

Structures

• Note
• Service Status
• User
• O Auth Token

Note

Class Name

Note

Fields

Name	Type	Tags	Description
id	Long	Required	-
title	String	Required	-
body	String	Required	-
user_id	Long	Required	-
created_at	String	Required	-
updated_at	String	Required	-

Example (as JSON)

{
  "id": 112,
  "title": "title4",
  "body": "body6",
  "user_id": 208,
  "created_at": "created_at2",
  "updated_at": "updated_at4"
}

Service Status

Class Name

ServiceStatus

Fields

Name	Type	Tags	Description
app	String	Required	-
moto	String	Required	-
notes	Integer	Required	-
users	Integer	Required	-
time	String	Required	-
os	String	Required	-
php_version	String	Required	-
status	String	Required	-

Example (as JSON)

{
  "app": "app2",
  "moto": "moto8",
  "notes": 134,
  "users": 202,
  "time": "time0",
  "os": "os8",
  "php_version": "php_version4",
  "status": "status8"
}

User

Class Name

User

Fields

Name	Type	Tags	Description
id	Integer	Required	-
name	String	Required	-
email	String	Required	-
created_at	String	Required	-
updated_at	String	Required	-

Example (as JSON)

{
  "id": 112,
  "name": "name0",
  "email": "email6",
  "created_at": "created_at2",
  "updated_at": "updated_at4"
}

O Auth Token

OAuth 2 Authorization endpoint response

Class Name

OAuthToken

Fields

Name	Type	Tags	Description
access_token	String	Required	Access token
token_type	String	Required	Type of access token
expires_in	Long	Optional	Time in seconds before the access token expires
scope	String	Optional	List of scopes granted This is a space-delimited list of strings.
expiry	Long	Optional	Time of token expiry as unix timestamp (UTC)
refresh_token	String	Optional	Refresh token Used to get a new access token when it expires.

Example (as JSON)

{
  "access_token": "access_token8",
  "token_type": "token_type2",
  "expires_in": null,
  "scope": null,
  "expiry": null,
  "refresh_token": null
}

Enumerations

• O Auth Provider Error

O Auth Provider Error

OAuth 2 Authorization error codes

Class Name

OAuthProviderErrorEnum

Fields

Name	Description
INVALID_REQUEST	The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.
INVALID_CLIENT	Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method).
INVALID_GRANT	The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.
UNAUTHORIZED_CLIENT	The authenticated client is not authorized to use this authorization grant type.
UNSUPPORTED_GRANT_TYPE	The authorization grant type is not supported by the authorization server.
INVALID_SCOPE	The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.

Exceptions

• O Auth Provider

O Auth Provider

OAuth 2 Authorization endpoint exception.

Class Name

OAuthProviderException

Fields

Name	Type	Tags	Description
error	OAuthProviderErrorEnum	Required	Gets or sets error code.
error_description	String	Optional	Gets or sets human-readable text providing additional information on error. Used to assist the client developer in understanding the error that occurred.
error_uri	String	Optional	Gets or sets a URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.

Example (as JSON)

{
  "error": "invalid_request",
  "error_description": null,
  "error_uri": null
}

Utility Classes Documentation

ApiHelper Class

API utility class.

Methods

Name	Return Type	Description
json_deserialize	Hash	Deserializes a JSON string to a Ruby Hash.
rfc3339	DateTime	Safely converts a string into an RFC3339 DateTime object.

Common Code Documentation

HttpResponse

Http response received.

Properties

Name	Type	Description
status_code	Integer	The status code returned by the server.
reason_phrase	String	The reason phrase returned by the server.
headers	Hash	Response headers.
raw_body	String	Response body.
request	HttpRequest	The request that resulted in this response.

HttpRequest

Represents a single Http Request.

Properties

Name	Type	Tag	Description
http_method	HttpMethodEnum		The HTTP method of the request.
query_url	String		The endpoint URL for the API request.
headers	Hash	Optional	Request headers.
parameters	Hash	Optional	Request body.