Good REST API design - read, learn, create!

restful api

REST API design is still a topic under discussion. I'll try to collect list of resources for web developers who want get deeper into it.

Free e-books

Start with Apigee: Web API Design.

Continue with more advanced topics in Thoughts on RESTful API Design .

Addtional interesting apects are covered in HTTP API Design Guide

To get brief understanding on different aspects of API variations refer to Undisturbed REST. Also it covers some instruments for building and prototyping APIs.

Non free books

If you want even more additional info and "other points of view"

Play

  • Apiary - powerful service to design, prototype, document and test APIs.
  • MuleSoft. Anypoint Platform - Complete platform with API Design Studio for API protyping and documentation.

Specifications / Auto docs

RESTful API concepts are clear, but big and complex app still require more predictable way to organize APIs. People try to find a way to provide standartized way for documenting and organizing REST API protocol.

  • Swagger - is a simple yet powerful representation of your RESTful API. Provides tools and standard to create GUI for API docs exploration and testing.
  • RAML - RESTful API Modeling Language (RAML) makes it easy to manage the whole API lifecycle from design to sharing.
  • JSONAPI - a specification for building apis in JSON. With the aim to make API response data normalized and API self explanatory.

Framework specific


Why I don't like HTML surrogate template engines

Preamble

Mostly it is about template engines (that hide away real HTML) in Ruby (as due to app runtime specific it is very easy to add pre-compiled "sweets" there, and everybody do it). But in general such tpl engines could exist in any server side language.
I don't like DSLs and abstractions that lead me away from the "origin". Ok, a careful reader have already got what will I write further :)
This post is not about "stop using it" or "it is bad", it is about "reconsider is it really so useful".

Let's start with examples

This just a small subset of all existing engines, that I have herd of, just to have an examples. Each language has it's specific, but mostly script web languages are good template engenes by themselves.

And I am really absolutely fine with most of them. Except those that force own HTML-replacement surrogate (it is Slim, HAML or JADE like).

 body
    h1 Markup examples

    #content
      p This example shows you how a basic Slim file looks like.

      == yield

      - unless items.empty?
        table
          - items.each do |item|
            tr
              td.name = item.name
              td.price = item.price
      - else
        p
         | No items found.  Please add some inventory.
           Thank you!

And now I'll try to explain this...


Read more ...

Yii2 component: yii2-gon. Push variables from PHP to JS.

This component publishes json serialisable data as 'key -> value' from PHP code into global JS variable window.gon.

Why?

The need for such an extensions came while working on web apps with mixed approach: rich JavaScript GUI on web page, but each page is reloaded and most of bussiness logic is still on the backend side.

The simples solution for a quick prototyping is pushing a data from PHP controller to global JS variable. That makes you free from a lot of REST API getters (you can make a lot without an API at all). So I did the first protype of this extension during "EU Web Challenge 2015" tasks coding. And now publish it as a standalone package.

Idea is inspired by Ruby gem gon https://github.com/gazay/gon (the name is taken from it too. "GON" authors - in case of any naming issues, just ping me :))


Read more ...

Local tunnels. Exposes your localhost dev server to global internet.

The solution for a question "how do I expose a local server behind a NAT or firewall to the internet?". Literally when your dev machine does not have a dedicated IP, but you need to...

  • make a demo of localhost web app (and can not deploy it to some server)
  • make a quick test of web app (api) on your mobile device
  • accept a webhook from some service or oAuth redirect

Local tunnels allows you to easily share a local web service development machine without messing with DNS and firewall settings. And here are some free tools...


Read more ...

Fix issues with Ruby installation (via rvm) in Ubuntu 15.10

ruby Got an error while trying to install Ruby via RVM and RBENV on Ubuntu 15.10.

compiling ossl_ssl.c
ossl_ssl.c:141:27: error: ‘SSLv3_method’ undeclared here (not in a function)
     OSSL_SSL_METHOD_ENTRY(SSLv3),
...
Makefile:293: recipe for target 'ossl_ssl.o' failed
make[2]: *** [ossl_ssl.o] Error 1
...
exts.mk:201: recipe for target 'ext/openssl/all' failed
make[1]: *** [ext/openssl/all] Error 2
...
make: *** [build-ext] Error 2

Solution #1

Apply patch during installation

curl -fsSL https://gist.github.com/mislav/055441129184a1512bb5.txt | rbenv install --patch 2.2.3

Read more ...
Ievgen
Kuzminov "iJackUA"
Web Team Lead
at MobiDev (Kharkiv, Ukraine)
Code in PHP and Ruby, play with JS/Node.JS, evaluate Elixir, explore databases, use Ubuntu and MacOS, think about IT people and management

Notes


Ansistrano- ansistrano.deploy and ansistrano.rollback are Ansible Galaxy roles to easily manage the deployment process for scripting applications such as PHP, Python and Ruby. It's an Ansible port for Capistrano.