Medium SDK for Ruby

Description

A Ruby SDK for the Medium.com API including:

Auth via OAuth 2.0 with automatic token refresh and demo app. This is necessary to request the listPublications or uploadImage access scopes.
Auth via integration token with demo app
Get and Post convenience methods
Raw HTTP methods via Faraday client useful for image upload
Swagger 2.0 spec in YAML and JSON

Installation

Via Bundler

Add medium_sdk to Gemfile and then run bundle:

$ echo "gem 'medium_sdk'" >> Gemfile
$ bundle

Via RubyGems

$ gem install medium_sdk

Usage

Authorization

Authorization Code Grant

The OAuth 2.0 authorization code grant is designed for where authorization needs to be granted by a 3rd party resource owner. This is required if your app wishes to request the listPublications or uploadImage scopes.

Initializing the SDK with the client_id parameter will use MediumSdk::Connection::AuthCode to manage the connection
Token refresh is automatically / transparently handled by FaradayMiddleware::OAuth2Refresh

require 'medium_sdk'

# Initialize SDK with OAuth redirect URI
client = MediumSdk.new(
  client_id: 'my_client_id',
  client_secret: 'my_client_secret',
  redirect_uri: 'https://example.com/callback/medium'
)

# Retrieve OAuth authorize url using default redirect URL
auth_url = client.connection.authorize_uri(
  scope: 'basicProfile,listPublications,publishPost',
  state: 'myState'
)

On your redirect page, you can exchange your authorization code for an access token using the following:

code  = params['code'] # e.g. using Sinatra to retrieve code param in Redirect URI
client.connection.authorize_code(code)

You can also save and load tokens for use across SDK instances:

# Access `OAuth2::AccessToken` object as hash including `access_token`, `refresh_token`, etc.
token_hash = client.connection.token.to_hash

# set_token() accepts a hash or OAuth2::AccessToken object
client.connection.set_token(token_hash)

Integration Token

Initializing the SDK with the integration_token and not the client_id parameter will use MediumSdk::Connection::IntegrationToken to manage the connection.

require 'medium_sdk'

# Initialize SDK with integration token
client = MediumSdk.new integration_token: token

# Set integration token after initialization
client.connection.token = token

Resource Methods

See the Swagger 2.0 spec in YAML and JSON for more info.

Users

Getting the authenticated user’s details

# Getting the authenticated user’s details
data = client.me

Publications

Listing the user’s publications

# Listing the user’s publications
data = client.user_publications           # uses authorized user's userId
data = client.user_publications 'user_id' # uses explicit userId

Fetching contributors for a publication

# Fetching contributors for a publication
data = client.publication_contributors 'publication_id'

Posts

Creating a post

# Creating a user post
data = client.post, {
  title: "Hard things in software development",
  contentFormat: "html",
  content: "<p>Cache invalidation</p><p>Naming things</p>",
  tags: ["development", "design"],
  publishStatus: "draft"
}

# Creating a backdated user post using `publishedAt` and `notifyFollowers`
data = client.post, {
  title: "Hard things in software development",
  contentFormat: "html",
  content: "<p>Cache invalidation</p><p>Naming things</p>",
  tags: ["development", "design"],
  publishStatus: "public",
  publishedAt: "2016-08-12T00:00:00+00:00",
  notifyFollowers: false
}

Creating a post under a publication

# Creating a publication post using `publicationId`
data = client.post, {
  title: "Hard things in software development",
  contentFormat: "html",
  content: "<p>Cache invalidation</p><p>Naming things</p>",
  tags: ["development", "design"],
  publishStatus: "public",
  publicationId: "b45573563f5a"
}

Images

Uploading an image

# Upload image
payload = {
  image: Faraday::UploadIO.new('/path/to/my_image.jpg', 'image/jpeg')
}
response = client.connection.http.post 'images', payload

Raw HTTP Client

The SDK's Faraday client can be accessed for sending raw requests. This can be used to upload images using Faraday::UploadIO.

response = client.connection.http.get 'me'

response = client.connection.http do |req|
  req.url 'me'
end

See the Faraday project for more info.

Swagger Spec

A Swagger 2.0 spec is included with this SDK for reference.

Format	Validation
`JSON Spec`	Validate JSON
`YAML Spec`	Validate YAML

Demos

Demos are in the scripts directory and use .env files for configuration.

Integration Token Demo

$ cd scripts
$ cp example.env .env
$ vi .env
$ ruby me_token.rb

OAuth 2.0 Demo

Execute the following and then go to the URL in your browser after launching the Sinatra app.

$ cd scripts/sinatra
$ bundle
$ cp example.env .env
$ vi .env
$ ruby app.rb

Change Log

See CHANGELOG.md

Credits

Swagger validation and YAML-to-JSON conversion by swagger-parser.

Contributing

Fork it ( http://github.com/grokify/medium-sdk-ruby/fork )
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

License

Medium SDK for Ruby is available under an MIT-style license. See LICENSE.txt for details.