Introdução ao Spring REST Shell

1. Visão geral

Neste artigo, daremos uma olhada no Spring REST Shell e alguns de seus recursos.

É uma extensão do Spring Shell, então recomendamos a leitura deabout it primeiro.

2. Introdução

O Spring REST Shell é um shell de linha de comando projetado para facilitar o trabalho com recursos REST compatíveis com Spring HATEOAS.

Não precisamos mais manipular as URLs no bash usando ferramentas comocurl. Spring REST Shell fornece uma maneira mais conveniente de interagir com recursos REST.

3. Instalação

Se estivermos usando uma máquina macOS com Homebrew, podemos simplesmente executar o próximo comando:

brew install rest-shell

Para usuários de outros sistemas operacionais, precisamos baixar um pacote binário dethe official GitHub project page, descompactar o pacote e encontrar um executável para executar:

tar -zxvf rest-shell-1.2.0.RELEASE.tar.gz
cd rest-shell-1.2.0.RELEASE
bin/rest-shell

Outra opção é baixar o código fonte e executar uma tarefa Gradle:

git clone git://github.com/spring-projects/rest-shell.git
cd rest-shell
./gradlew installApp
cd build/install/rest-shell-1.2.0.RELEASE
bin/rest-shell

Se tudo estiver configurado corretamente, veremos a seguinte saudação:

 ___ ___  __ _____  __  _  _     _ _  __
| _ \ __/' _/_   _/' _/| || |   / / | \ \
| v / _|`._`. | | `._`.| >< |  / / /   > >
|_|_\___|___/ |_| |___/|_||_| |_/_/   /_/
1.2.1.RELEASE

Welcome to the REST shell. For assistance hit TAB or type "help".
http://localhost:8080:>

4. Começando

Estaremos trabalhando com a APIalready developed for another article. Olocalhost:8080 é usado como um URL base.

Aqui está uma lista de endpoints expostos:

OBTER/articles - obter todos osArticles
GET/articles/{id} - obtém umArticle por id
GET/articles/search/findByTitle?title={title} - obtém umArticle por título
GET / profile / articles - obtém os dados do perfil para um recursoArticle
POST/articles - cria um novoArticle com um corpo fornecido

A classeArticle tem três campos:id, title, econtent.

4.1. Criação de novos recursos

Vamos adicionar um novo artigo. Vamos usarthe post command passing a JSON String with the –data parameter.

Primeiro, precisamosfollow a URL associada ao recurso que queremos adicionar. O comandofollow pega um URI relativo, concatena-o combaseUrie define o resultado como a localização atual:

http://localhost:8080:> follow articles
http://localhost:8080/articles:> post --data "{title: "First Article"}"

O resultado da execução do comando será:

< 201 CREATED
< Location: http://localhost:8080/articles/1
< Content-Type: application/hal+json;charset=UTF-8
< Transfer-Encoding: chunked
< Date: Sun, 29 Oct 2017 23:04:43 GMT
<
{
  "title" : "First Article",
  "content" : null,
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/articles/1"
    },
    "article" : {
      "href" : "http://localhost:8080/articles/1"
    }
  }
}

4.2. Descobrindo Recursos

Agora, quando tivermos alguns recursos, vamos descobri-los. Vamos usarthe discover command which reveals all available resources at the current URI:

http://localhost:8080/articles:> discover

rel        href
=================================================
self       http://localhost:8080/articles/
profile    http://localhost:8080/profile/articles
article    http://localhost:8080/articles/1

Conhecendo o URI do recurso, podemos buscá-lo usando o comandoget:

http://localhost:8080/articles:> get 1

> GET http://localhost:8080/articles/1

< 200 OK
< Content-Type: application/hal+json;charset=UTF-8
< Transfer-Encoding: chunked
< Date: Sun, 29 Oct 2017 23:25:36 GMT
<
{
  "title" : "First Article",
  "content" : null,
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/articles/1"
    },
    "article" : {
      "href" : "http://localhost:8080/articles/1"
    }
  }
}

4.3. Adicionando Parâmetros de Consulta

Podemos especificar parâmetros de consulta como fragmentos JSON usando o parâmetro–params.

Vamos pegar um artigo com o título dado:

http://localhost:8080/articles:> get search/findByTitle \
> --params "{title: "First Article"}"

> GET http://localhost:8080/articles/search/findByTitle?title=First+Article

< 200 OK
< Content-Type: application/hal+json;charset=UTF-8
< Transfer-Encoding: chunked
< Date: Sun, 29 Oct 2017 23:39:39 GMT
<
{
  "title" : "First Article",
  "content" : null,
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/articles/1"
    },
    "article" : {
      "href" : "http://localhost:8080/articles/1"
    }
  }
}

4.4. Configurando cabeçalhos

The command called headers allows managing headers within the session scope - todas as solicitações serão enviadas usando esses cabeçalhos. Oheaders set usa os argumentos–namee–value para determinar um cabeçalho.

Vamos adicionar alguns cabeçalhos e fazer uma solicitação, incluindo os seguintes:

http://localhost:8080/articles:>
  headers set --name Accept --value application/json

{
  "Accept" : "application/json"
}

http://localhost:8080/articles:>
  headers set --name Content-Type --value application/json

{
  "Accept" : "application/json",
  "Content-Type" : "application/json"
}

http://localhost:8080/articles:> get 1

> GET http://localhost:8080/articles/1
> Accept: application/json
> Content-Type: application/json

4.5. Gravando resultados em um arquivo

Nem sempre é desejável imprimir os resultados de uma solicitação HTTP na tela. Sometimes, we need to save the results in a file for further analysis.

O parâmetro–output permite realizar tais operações:

http://localhost:8080/articles:> get search/findByTitle \
> --params "{title: "First Article"}" \
> --output first_article.txt

>> first_article.txt

4.6. Ler JSON de um arquivo

Freqüentemente, os dados JSON são muito grandes ou muito complexos para serem inseridos por meio do console usando o parâmetro–data.

Além disso, existem algumas limitações no formato dos dados JSON que podemos inserir diretamente na linha de comandos.

O parâmetro–from dá a possibilidade de ler dados de um arquivo ou diretório.

Se o valor for um diretório, o shell irá ler cada arquivo que termina com“.json”e realizar um POST ou PUT com o conteúdo desse arquivo.

Se o parâmetro for um arquivo, o shell carregará o arquivo e os dados POST / PUT desse arquivo.

Vamos criar o próximo artigo do arquivosecond_article.txt:

http://localhost:8080/articles:> post --from second_article.txt

1 files uploaded to the server using POST

4.7. Configurando Variáveis de Contexto

Também podemos definir variáveis dentro do contexto atual da sessão. The command var defines the get and set parameters for getting and setting a variable respectively.

Por analogia comheaders, os argumentos–namee–value são para dar o nome e o valor de uma nova variável:

http://localhost:8080:> var set --name articlesURI --value articles
http://localhost:8080/articles:> var get --name articlesURI

articles

Agora, vamos imprimir uma lista de variáveis atualmente disponíveis dentro do contexto:

http://localhost:8080:> var list

{
  "articlesURI" : "articles"
}

Tendo certeza de que nossa variável foi salva, vamos usá-la com o comandofollow para mudar para o URI fornecido:

http://localhost:8080:> follow #{articlesURI}
http://localhost:8080/articles:>

4.8. Vendo histórico

Todos os caminhos que visitamos são registrados. The command history shows these paths in the chronological order:

http://localhost:8080:> history list

1: http://localhost:8080/articles
2: http://localhost:8080

Cada URI está associado a um número que pode ser usado para acessar esse URI:

http://localhost:8080:> history go 1
http://localhost:8080/articles:>

5. Conclusão

Neste tutorial, nos concentramos em uma ferramenta interessante e rara no ecossistema Spring - uma ferramenta de linha de comando.

Você pode encontrar mais informações sobre o projetoover on GitHub.

E, como sempre, todos os trechos de código mencionados no artigo podem ser encontrados emour repository.

TOC

Introdução ao Spring REST Shell