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

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.