An app to browse, documentate, discover REST APIs
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
assets
css
dist
samples
scripts
semantic
src
.babelrc
.eslintrc
.gitignore
.jshintrc
.travis.yml
LICENSE
Makefile
README.md
conf.js
index.html
package.json
semantic.json
server.js
webpack.config.js
webpack.prod.config.js

README.md

Build Status

ExploREST

An app to browse, documentate, discover REST APIs

ExploREST is an application that you can use to documentate your REST API, to make presentations or show easily how beautiful your API is.
If you look at a classic API documentation, it is often quite complicated. With ExploREST, you take the user by the hand and show him how your application works by simply cliking on links, that will POST, PUT, DELETE or simply GET !

Don't believe me, go try it: http://explorest.herokuapp.com

app screenshot

Features:

  • Cross-resource exploration: when a resource has a link to another resource, you can directly click it to access it.
  • Formatted, highlighted JSON.
  • Markdown to documentate your API
  • Playground links: insert them in you Markdown. When you click on them, if makes a get request and diplays the result !
  • Sample links: idem. When you click on them, it makes the POST, PUT or DELETE requests you specified in the Markdown. It is very practical for demonstrations, or to communicate with someone else: instead of making a curl (more efforts needed), put a sample link into the markdown for once. Now other people just have to click it !

Note that I did this project on my own, so it is not fully tested and documented yet. But there is a good base (I hope)

Requirement : (some versions bellow should work too but have not been tested)

  • nodeJS: >=6
  • npm: >=3.8.9

NB. an easy way to install both, whatever the version of node you already have, is to install nvm :

sudo apt-get update
sudo apt-get install build-essential libssl-dev
curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.32.0/install.sh | bash
nvm install v6.2.0

Build and run :

git clone https://github.com/Romathonat/ExploREST.git
npm install
npm run dev

You can go to http://localhost:3000/.

Then, you need to enter the URL of the server you want to work on on the input at the top of the page (without "/" at the end)

FAQ

  • What is a playground link and how to create it ?
    A playground link is a clickable link that make a GET request on the API and displays its content in the codeview. To do so, create a classic link in markdown, and make your URL begin with "/"
    example:
[/resources/compute](/resources/compute)
  • What is a sample link and how to create it ?
    A sample link is a link that post datas onto the current server when clicking on it. The formating is as follow (in markdown):
text before %{
  "text": "sampleLink",
  "post": {
    "address": "/character",
    "data": {
      "name":"Dark Vador",
      "type": "sith"
    }
  }
}% text after

It will result in a clickable link, which will post or put datas on click:

<p>text before <a>sampleLink</a> text after</p>

You can post an array instead of an object (in the "datas" attribute). It can be put instead of posted, by using the "put" key instead of the "post" one.

If you want your sample link to post to different locations, just put an array instead of an object inside the "post" attribute. Example :

%{
  "text": "sampleLink",
  "post": [
    {
      "adress": "/character",
      "datas": {
         "name": "Leia",
         "type": "princess"
       }
    },
    {
        "address": "/soldier",
        "datas": [
            {
              "name": "Francis",
              "type": "stormtrooper"
            },
            {
              "name": "Michel",
              "type": "stormtrooper"
            }
        ]
    }
  ]
}%
  • Can I delete datas with a sample link ?
    Yes, you can, with the following format :
%{
  "text": "my sample link",
  "del": "/6df690d2-3158-40c4-88fb-d1c41584d6e7"
}%
  • I want to use this tool to documentate my own REST API, I need to add headers for the authentification, hox to do it ? Go to the conf.js file, and add the headers you want in the headers variable.

  • How to deploy on Heroku ?

#need to be done once
heroku git:remote -a herokuRepo 
npm run build
git commit -am "deployment message"
git push heroku master