The following is an extract from our book, HTML5 & CSS3 for the Real World, 2nd Edition, written by Alexis Goldstein, Louis Lazaris, and Estelle Weyl. Copies are sold in stores worldwide, or you can buy it in ebook form here. In Chapter 2 and Chapter 3, we covered considerable ground explaining how our pages […]
Continue reading %Improve Your Website’s Accessibility With WAI-ARIA%
Nowadays it is a common practice to rely heavily on APIs (application programming interfaces). Not only big services like Facebook and Twitter employ them—APIs are very popular due to the spread of client-side frameworks like React, Angular, and many others. Ruby on Rails is following this trend, and the latest version presents a new feature allowing you to create API-only applications.
Initially this functionality was packed into a separate gem called rails-api, but since the release of Rails 5, it is now part of the framework's core. This feature along with ActionCable was probably the most anticipated, and so today we are going to discuss it.
This article covers how to create API-only Rails applications and explains how to structure your routes and controllers, respond with the JSON format, add serializers, and set up CORS (Cross-Origin Resource Sharing). You will also learn about some options to secure the API and protect it from abuse.
The source for this article is available at GitHub.
To start off, run the following command:
rails new RailsApiDemo --api
It is going to create a new API-only Rails application called RailsApiDemo. Don't forget that the support for the --api option was added only in Rails 5, so make sure you have this or a newer version installed.
Open the Gemfile and note that it is much smaller than usual: gems like coffee-rails, turbolinks, and sass-rails are gone.
The config/application.rb file contains a new line:
config.api_only = true
It means that Rails is going to load a smaller set of middleware: for instance, there's no cookies and sessions support. Moreover, if you try to generate a scaffold, views and assets won't be created. Actually, if you check the views/layouts directory, you'll note that the application.html.erb file is missing as well.
Another important difference is that the ApplicationController inherits from the ActionController::API, not ActionController::Base.
That's pretty much it—all in all, this is a basic Rails application you've seen many times. Now let's add a couple of models so that we have something to work with:
rails g model User name:string rails g model Post title:string body:text user:belongs_to rails db:migrate
Nothing fancy is going on here: a post with a title, and a body belongs to a user.
Ensure that the proper associations are set up and also provide some simple validation checks:
has_many :posts validates :name, presence: true
belongs_to :user validates :title, presence: true validates :body, presence: true
Brilliant! The next step is to load a couple of sample records into the newly created tables.
The easiest way to load some data is by utilizing the seeds.rb file inside the db directory. However, I am lazy (as many programmers are) and don't want to think of any sample content. Therefore, why don't we take advantage of the faker gem that can produce random data of various kinds: names, emails, hipster words, "lorem ipsum" texts, and much more.
group :development do
gem 'faker'
end
Install the gem:
bundle install
Now tweak the seeds.rb:
5.times do
user = User.create({name: Faker::Name.name})
user.posts.create({title: Faker::Book.title, body: Faker::Lorem.sentence})
end
Lastly, load your data:
rails db:seed
Now, of course, we need some routes and controllers to craft our API. It's a common practice to nest the API's routes under the api/ path. Also, developers usually provide the API's version in the path, for example api/v1/. Later, if some breaking changes have to be introduced, you can simply create a new namespace (v2) and a separate controller.
Here is how your routes can look:
namespace 'api' do
namespace 'v1' do
resources :posts
resources :users
end
end
This generates routes like:
api_v1_posts GET /api/v1/posts(.:format) api/v1/posts#index
POST /api/v1/posts(.:format) api/v1/posts#create
api_v1_post GET /api/v1/posts/:id(.:format) api/v1/posts#show
You may use a scope method instead of the namespace, but then by default it will look for the UsersController and PostsController inside the controllers directory, not inside the controllers/api/v1, so be careful.
Create the api folder with the nested directory v1 inside the controllers. Populate it with your controllers:
module Api
module V1
class UsersController < ApplicationController
end
end
end
module Api
module V1
class PostsController < ApplicationController
end
end
end
Note that not only do you have to nest the controller's file under the api/v1 path, but the class itself also has to be namespaced inside the Api and V1 modules.
The next question is how to properly respond with the JSON-formatted data? In this article we will try these solutions: the jBuilder and active_model_serializers gems. So before proceeding to the next section, drop them into the Gemfile:
gem 'jbuilder', '~> 2.5' gem 'active_model_serializers', '~> 0.10.0'
Then run:
bundle install
jBuilder is a popular gem maintained by the Rails team that provides a simple DSL (domain-specific language) allowing you to define JSON structures in your views.
Suppose we wanted to display all the posts when a user hits the index action:
def index
@posts = Post.order('created_at DESC')
end
All you need to do is create the view named after the corresponding action with the .json.jbuilder extension. Note that the view must be placed under the api/v1 path as well:
json.array! @posts do |post| json.id post.id json.title post.title json.body post.body end
json.array! traverses the @posts array. json.id, json.title and json.body generate the keys with the corresponding names setting the arguments as the values. If you navigate to http://localhost:3000/api/v1/posts.json, you'll see an output similar to this one:
[
{"id": 1, "title": "Title 1", "body": "Body 1"},
{"id": 2, "title": "Title 2", "body": "Body 2"}
]
What if we wanted to display the author for each post as well? It's simple:
json.array! @posts do |post|
json.id post.id
json.title post.title
json.body post.body
json.user do
json.id post.user.id
json.name post.user.name
end
end
The output will change to:
[
{"id": 1, "title": "Title 1", "body": "Body 1", "user": {"id": 1, "name": "Username"}}
]
The contents of the .jbuilder files is plain Ruby code, so you may utilize all the basic operations as usual.
Note that jBuilder supports partials just like any ordinary Rails view, so you may also say:
json.partial! partial: 'posts/post', collection: @posts, as: :post
and then create the views/api/v1/posts/_post.json.jbuilder file with the following contents:
json.id post.id
json.title post.title
json.body post.body
json.user do
json.id post.user.id
json.name post.user.name
end
So, as you see, jBuilder is easy and convenient. However, as an alternative, you may stick with the serializers, so let's discuss them in the next section.
The rails_model_serializers gem was created by a team who initially managed the rails-api. As stated in the documentation, rails_model_serializers brings convention over configuration to your JSON generation. Basically, you define which fields should be used upon serialization (that is, JSON generation).
Here is our first serializer:
class PostSerializer < ActiveModel::Serializer attributes :id, :title, :body end
Here we say that all these fields should be present in the resulting JSON. Now methods like to_json and as_json called upon a post will use this configuration and return the proper content.
In order to see it in action, modify the index action like this:
def index
@posts = Post.order('created_at DESC')
render json: @posts
end
as_json will automatically be called upon the @posts object.
What about the users? Serializers allow you to indicate relations, just like models do. What's more, serializers can be nested:
class PostSerializer < ActiveModel::Serializer
attributes :id, :title, :body
belongs_to :user
class UserSerializer < ActiveModel::Serializer
attributes :id, :name
end
end
Now when you serialize the post, it will automatically contain the nested user key with its id and name. If later you create a separate serializer for the user with the :id attribute excluded:
class UserSerializer < ActiveModel::Serializer
attributes :name
end
then @user.as_json won't return the user's id. Still, @post.as_json will return both the user's name and id, so bear it in mind.
In many cases, we don't want anyone to just perform any action using the API. So let's present a simple security check and force our users to send their tokens when creating and deleting posts.
The token will have an unlimited life span and be created upon the user's registration. First of all, add a new token column to the users table:
rails g migration add_token_to_users token:string:index
This index should guarantee uniqueness as there can't be two users with the same token:
add_index :users, :token, unique: true
Apply the migration:
rails db:migrate
Now add the before_save callback:
before_create -> {self.token = generate_token}
The generate_token private method will create a token in an endless cycle and check whether it is unique or not. As soon as a unique token is found, return it:
private
def generate_token
loop do
token = SecureRandom.hex
return token unless User.exists?({token: token})
end
end
You may use another algorithm to generate the token, for example based on the MD5 hash of the user's name and some salt.
Of course, we also need to allow users to register, because otherwise they won't be able to obtain their token. I don't want to introduce any HTML views into our application, so instead let's add a new API method:
def create
@user = User.new(user_params)
if @user.save
render status: :created
else
render json: @user.errors, status: :unprocessable_entity
end
end
private
def user_params
params.require(:user).permit(:name)
end
It's a good idea to return meaningful HTTP status codes so that developers understand exactly what is going on. Now you may either provide a new serializer for the users or stick with a .json.jbuilder file. I prefer the latter variant (that's why I do not pass the :json option to the render method), but you are free to choose any of them. Note, however, that the token must not be always serialized, for example when you return a list of all users—it should be kept safe!
json.id @user.id json.name @user.name json.token @user.token
The next step is to test if everything is working properly. You may either use the curl command or write some Ruby code. Since this article is about Ruby, I'll go with the coding option.
To perform an HTTP request, we will employ the Faraday gem, which provides a common interface over many adapters (the default is Net::HTTP). Create a separate Ruby file, include Faraday, and set up the client:
require 'faraday'
client = Faraday.new(url: 'http://localhost:3000') do |config|
config.adapter Faraday.default_adapter
end
response = client.post do |req|
req.url '/api/v1/users'
req.headers['Content-Type'] = 'application/json'
req.body = '{ "user": {"name": "test user"} }'
end
All these options are pretty self-explanatory: we choose the default adapter, set the request URL to http://localhost:300/api/v1/users, change the content type to application/json, and provide the body of our request.
The server's response is going to contain JSON, so to parse it I'll use the Oj gem:
require 'oj' # client here... puts Oj.load(response.body) puts response.status
Apart from the parsed response, I also display the status code for debugging purposes.
Now you can simply run this script:
ruby api_client.rb
and store the received token somewhere—we'll use it in the next section.
To enforce the token authentication, the authenticate_or_request_with_http_token method can be used. It is a part of the ActionController::HttpAuthentication::Token::ControllerMethods module, so don't forget to include it:
class PostsController < ApplicationController
include ActionController::HttpAuthentication::Token::ControllerMethods
# ...
end
Add a new before_action and the corresponding method:
before_action :authenticate, only: [:create, :destroy]
# ...
private
# ...
def authenticate
authenticate_or_request_with_http_token do |token, options|
@user = User.find_by(token: token)
end
end
Now if the token is not set or if a user with such token cannot be found, a 401 error will be returned, halting the action from executing.
Do note that the communication between the client and the server has to be made over HTTPS, because otherwise the tokens may be easily spoofed. Of course, the provided solution is not ideal, and in many cases it is preferable to employ the OAuth 2 protocol for authentication. There are at least two gems that greatly simplify the process of supporting this feature: Doorkeeper and oPRO.
To see our authentication in action, add the create action to the PostsController:
def create
@post = @user.posts.new(post_params)
if @post.save
render json: @post, status: :created
else
render json: @post.errors, status: :unprocessable_entity
end
end
We take advantage of the serializer here to display the proper JSON. The @user was already set inside the before_action.
Now test everything out using this simple code:
client = Faraday.new(url: 'http://localhost:3000') do |config|
config.adapter Faraday.default_adapter
config.token_auth('127a74dbec6f156401b236d6cb32db0d')
end
response = client.post do |req|
req.url '/api/v1/posts'
req.headers['Content-Type'] = 'application/json'
req.body = '{ "post": {"title": "Title", "body": "Text"} }'
end
Replace the argument passed to the token_auth with the token received upon registration, and run the script.
ruby api_client.rb
Deletion of a post is done in the same way. Add the destroy action:
def destroy
@post = @user.posts.find_by(params[:id])
if @post
@post.destroy
else
render json: {post: "not found"}, status: :not_found
end
end
We only allow users to destroy the posts they actually own. If the post is removed successfully, the 204 status code (no content) will be returned. Alternatively, you may respond with the post's id that was deleted as it will still be available from the memory.
Here is the piece of code to test this new feature:
response = client.delete do |req| req.url '/api/v1/posts/6' req.headers['Content-Type'] = 'application/json' end
Replace the post's id with a number that works for you.
If you want to enable other web services to access your API (from the client-side), then CORS (Cross-Origin Resource Sharing) should be properly set up. Basically, CORS allows web applications to send AJAX requests to the third-party services. Luckily, there is a gem called rack-cors that enables us to easily set everything up. Add it into the Gemfile:
gem 'rack-cors'
Install it:
bundle install
And then provide the configuration inside the config/initializers/cors.rb file. Actually, this file is already created for you and contains a usage example. You can also find some pretty detailed documentation on the gem's page.
The following configuration, for example, will allow anyone to access your API using any method:
Rails.application.config.middleware.insert_before 0, Rack::Cors do
allow do
origins '*'
resource '/api/*',
headers: :any,
methods: [:get, :post, :put, :patch, :delete, :options, :head]
end
end
The last thing I am going to mention in this guide is how to protect your API from abuse and denial of service attacks. There is a nice gem called rack-attack (created by people from Kickstarter) that allows you to blacklist or whitelist clients, prevent the flooding of a server with requests, and more.
Drop the gem into Gemfile:
gem 'rack-attack'
Install it:
bundle install
And then provide configuration inside the rack_attack.rb initializer file. The gem's documentation lists all the available options and suggests some use cases. Here is the sample config that restricts anyone except you from accessing the service and limits the maximum number of requests to 5 per second:
class Rack::Attack
safelist('allow from localhost') do |req|
# Requests are allowed if the return value is truthy
'127.0.0.1' == req.ip || '::1' == req.ip
end
throttle('req/ip', :limit => 5, :period => 1.second) do |req|
req.ip
end
end
Another thing that needs to be done is including RackAttack as a middleware:
config.middleware.use Rack::Attack
We've come to the end of this article. Hopefully, by now you feel more confident about crafting APIs with Rails! Do note that this is not the only available option—another popular solution that was around for quite some time is the Grape framework, so you may be interested in checking it out as well.
Don't hesitate to post your questions if something seemed unclear to you. I thank you for staying with me, and happy coding!
Do you run social media campaigns for the holidays? Wondering if social media efforts during holiday seasons impact sales? In this article, you’ll discover new research that shows why small businesses should maintain a consistent social presence all year long, and why small- and medium-sized businesses should participate in larger, holistic holiday campaigns. #1: Small [...]
This post Do Holiday Specials via Social Media Work? New Research first appeared on .
- Your Guide to the Social Media Jungle
OffCanvas is a lightweight, flexible jQuery off-canvas navigation plugin which lets you create fully accessible sidebar or top/bottom sliding (or push) panels with keyboard interactions and ARIA attributes.
Have you thought about where you will be in 52 weeks time?
Will 2017 be just another year, or will it be the year your product (or service, or experience) takes the world by storm?
The most successful projects often start by creating a clear vision of where you want to get to, and working backwards from there.
That’s why I love the aptly named ‘working backwards’ method. Most famously adopted by Amazon, it’s a method to create a customer-focused vision of your product’s future.
It starts by writing a press release.
That’s right. Before Amazon’s designers and developers start working on something new, they write a hypothetical press release from the future, celebrating the success of a product after its launch.
Because it’s written 12 months in the future, the ‘working backwards’ method forces you to dream big. To focus on your BHAGs (your Big Hairy Audacious Goals), and the the ground-breaking, game-changing changes you need to achieve them.
A well-crafted press release is a great use of good old storytelling. It gets the team excited and focussed before any lines of code are written.
It reduces waste because it keeps your team building the right things; if the press release isn’t worth reading, then it’s unlikely that anyone will be interested in you product either, which means you should probably think twice about building it.
You can find a tonne of different templates and formats of press releases online. Keep it to one page in length, and include the following:
Title: A catchy but clear summary of what you’ve achieved in the 52 weeks ahead of you.
The lead paragraph: The opening paragraph should summarise the successes you’ve achieved over the last 12 months, and how you’ve achieved them. And most of all, why they’re important to your customer. Like an elevator pitch, it should be well crafted and strong enough for the reader to read just this, and nothing else, to get the key details.
The target market: Writing a press release can help the team definite exactly who they’re targeting before they start building a product.
Problem / Solution: It’s important to describe your achievements from the customer’s viewpoint. Describe the actual problem that your customer has, and why this product solves that problem. What customer problem or task did you focus on in order to leapfrog towards your new-found success?
Quotes: Including quotes in your press release adds personality and emotion. Consider including a quote from a company spokesperson, or even a customer.
An image: Press releases with images are viewed and shared 3 times more, so make sure you’ve included a visionary concept of your future-product. Whether it’s a back-of-the-napkin sketch, or a pixel-perfect concept, thinking about what it looks like in the future can help bring your product to life.
Find out more: A quick summary, and an indication about where the user needs to go to learn more.
In my experience, the best results come from writing a press release collaboratively as a team, perhaps as a half-day workshop. This creates a shared understanding of your product vision, and how your roadmap will support that.
Once you’ve written your press release, don’t hide it away in a drawer and never look at it again. Make sure you:
Your press release should become the North Star for your product, and guide you towards making the right decisions to what to focus on 2017.
Where exactly do you want to be, one year from now?
This article was originally published for UXmas – an advent calendar for UX folk. Catch up on all 24 posts at uxmas.com.
The post Working backwards appeared first on UX Mastery.
