noosfero api Page History

Noosfero API

O noosfero permite a automação de dados através de uma simples e poderosa API RESTful.

Recursos

A documentação para vários recursos da API podem ser encontradas separadamente em:

Autenticação

Quase todas as requisições a API requerem autenticação. Você irá precisar prover um parâmetro private_token para as requisições. O private_token pode ser também providenciado via header, neste caso, seu nome deve ser PRIVATE-TOKEN.

Caso o private_token for emitido ou inválido, uma mensagem de erro com o código 401 será retornada:

{
    message: "Não autorizado",
    code: 401
}

As requisições à api devem ser prefixadas com api e a versão da API.

Exemplo de uma requisição válida a API:

GET https://softwarepublico.gov.br/social/api/v1/communities?private_token=insiraseutoken

Exemplo de requisição válida a API via curl com a autenticação utilizando o header

curl --header "PRIVATE-TOKEN: insiraseutoken" "https://softwarepublico.gov.br/social/api/v1/communities"

A API utiliza o json para serializar seus dados. você não precisa espeficar .json no final de uma URL.

Obtendo o token de autenticação

Para obter o token de autenticação no noosfero é necessário chamar a url POST api/v1/login com os parametros login e password. Isto pode ser feito com mais facilidade através do playground.

O retorno será o JSON usuário do login. Em um dos campos estará o private_token:

{
  "user": {
    "id": 51,
    "login": "adminuser",
    "email": "adminuser@localhost.localdomain",
    "activated": true,
    "person": {
      "identifier": "adminuser",
      "name": "adminuser",
      "id": 54,
      "created_at": "2016/01/27 17:12:15",
      "updated_at": "2016/01/27 17:12:19",
      "additional_data": {},
      "image": null,
      "region": null,
      "user": {
        "id": 51,
        "login": "adminuser"
      }
    },
    "permissions": {
      "use-organic-food": [
        "invite_members"
      ],
      "i-like-free-software": [
        "invite_members"
      ]
    },
    "private_token": "seuprivatetokenaqui"
  }
}

Códigos de status

A API é feita para retornar diferentes códigos de status de acordo com o contexto e a ação. Desta forma, se uma requisição encontrar um erro, o utilizador poderá ter uma idéia do que ocorreu de errado.

A seguinte tabela prove uma visão geral de como as funções da API geralmente se comportam.

Tipo da requisição Descrição
GET Accesa um ou mais recursos e retorna o resultado como um JSON.
POST Retorna 201 Created se foi criado com sucesso e retorna o recurso criado como JSON.
GET / PUT / DELETE Retorna 200 OK se acessado, modificado ou deletado com sucesso. O recurso (modificado) é retornado como JSON.
DELETE Feito para ter idempotência, significando que o recurso ainda retornará 200 OK mesmo se já tiver sido deletado antes e não estiver disponível. O motivo é que o usuário não está realmente interessado se o recurso já existia ou não.

A seguinte tabela mostra os possíveis códigos de retorno das requisições a API. The following table shows the possible return codes for API requests.

Valor de retorno Descrição
200 OK A requisição GET, PUT ou DELETE foi realizada com sucesso e o recurso(s) em si foram retornados como JSON.
201 Created A requisição POST foi realizado com sucesso e o recurso foi retornado como JSON.
400 Bad Request Um atributo requerido para requisição a API está faltando. Exemplo: o título de um artigo não foi dado.
401 Unauthorized O usuário não está autenticado, um token de usuário válido é necessário.
403 Forbidden A requisição não é permitida. Exemplo: O usuário não tem permissão de deletar um artigo.
404 Not Found O recurso não pode ser acessado. Exemplo: o ID do artigo não foi encontrado.
405 Method Not Allowed A requisição não é suportada.
409 Conflict Um recurso conflitante já existe. Exemplo: criar uma comunidade com um nome já existente.
422 Unprocessable A entidade não pode ser processada.
500 Server Error Algo deu errado ao processar alguma coisa no servidor.

Paginação

Algumas vezes o recurso retornado poderá vir em diversas páginas. Quando listando um recurso, você poderá passar os seguintes parâmetros.

Parâmetro Descrição
page Número da página (padrão: 1)
per_page Número de itens listados por página (padrão: 20, máximo: 100)

No exemplo abaixo, nós listamos 50 comunidades por página.

curl --header "PRIVATE-TOKEN: insiraseutoken" "https://softwarepublico.gov.br/social/api/v1/communities?per_page=50"

Playground

O noosfero disponibiliza uma interface de testes para a API na URL api/playground.

Está interface mostra todas as possíveis requisições(chamadas aqui de endpoints) e alguns dos parâmetros essenciais para o seu funcionamento. É possível chamar as requisições através da interface e observar o seu retorno no visualizador abaixo, já com o JSON formatado.

Last edited by Gust