rogerleite/_wapi_pt-br.md

WAPI - Web API Server Spec

por Roger Leite - 2012

Table of Contents

Web API Server Spec
Interfaces
Styles

Web API Server Spec

Introdução

O WAPI Server, é uma spec que descreve os componentes necessários para publicar um domínio. Os exemplos estão em Ruby, naturalmente fácil de entender.

Interfaces

Modelagem das responsabilidades das interfaces.

Domain

Domain é a classe que define:

[Config]
[Models]
[Style]
[Filters]

Config

O config deve ter os seguintes campos:

name # => "Song Domain"
env  # => :development (by default)
     # can be informed by environment, using WAPI_ENV variable.

Models

Mapa de modelos que o domínio atende.

Exemplo:

  SongDomain.models do

    # How to use model map.
    # name - name from resource

    model :artists
    model :albums
    model :songs

  end

Style

A principal função do Style é usar o domain para:

Criar rotas para os models.
Atender requests com um controller default, estilo inherit resources.
Registrar filters do Style.

No capítulo [RestfulByRos], você pode ver um exemplo de Style.

Filter

Funciona em chain como os Rack::Middleware. Durante o filtro, tem acesso a domain, request e response.

Styles

RestfulByRos

É o style que disponibiliza o seu domain usando o principio REST da tese Architectural Styles and the Design of Network-based Software Architectures do Roys Fielding.

OnBoot

Usar os models do domain para montar as rotas:

  # for Artist model that has many Albums. See Models chapter for example.
  /artists     [  POST] - To create.
               [   GET] - List with filter query params.
  /artists/new [   GET] - Describe model structure.
  /artists/:id [   GET] - Retrieve artist info.
               [   PUT] - List with filter query params.
               [DELETE] - List with filter query params.

  /albums      [  POST] - To create.
               [   GET] - List with filter query params.
  /albums/new  [   GET] - Describe model structure.
  /albums/:id  [   GET] - Retrieve artist info.
               [   PUT] - List with filter query params.
               [DELETE] - List with filter query params.

Adiciona filter CacheHeaders, responsável por adicionar http headers de cache.

Controller

Valida constraints do request.

Se o verbo usado não for permitido, retorna um 401 Unauthorized com header Allow incluíndo os VERBS permitidos.

Faz algo como Inherit Resources.

Segue as regras Restful de etiqueta.

Após post, retorna 201 Created com header Location com a url do documento.
Após put, TODO.
Após delete, TODO.
Após get, TODO.