RESTool 2.0 (demo)

The best tool in the neighborhood. Managing your RESTful APIs has never been so easy.

RESTool gives you an out of the box UI that connects to your RESTful API with a simple configuration file.

The idea behind it is simple. Given the fact that each entity in your API has a RESTful implementation, RESTool will provide you UI tool for managing these entities in no time by simply editing a configuration file. No front end engineers, no JavaScript, no CSS, no html. Just a simple JSON file.

Live Demo: https://dsternlicht.github.io/RESTool/

What's New in V2?
Getting started
Configuration
Development
Contributing

What's New in V2?

While RESTool originally was developed with Angular, we decided to rewrite it from scratch and move to React. The main reason we moved to React is the community. Since React is so popular we believe that choosing React over Angular will get a much wider community support.

Some new features and capabilities in V2:

From Angular to React & Typescript
Full mobile support
Cards layout
Custom app colors
Data path extraction from arrays
New & improved design
Internationalization (i18n) support with auto-detect browser language
Custom favicon support
Custom icons for actions
Better error handling in configuration and requests

Getting started

If you're only interested in using RESTool on its latest version as a management tool for your RESTful API, read the docs about configuration, deployment, and consuming RESTool from CDN.

If you wish to extend RESTool's functionality and develop on top of it, please go to the development section.

Configuration

One of the best things about RESTool (and the reason we actually built it) is that you don't need to develop anything. Everything is configurable and may be set simply by editing a configuration file (config.json).

The config.json file should be placed in the root folder of the project, alongside with the index.html file.

You can copy ./public/config-sample.json to ./public/config.json and adopt the settings to your liking.

Here's a detailed list of properties you could add to your configuration file (just in case, we added a config-sample.json file you could learn from).

| Property | Type | Required? | Description | |----------------|--------------|-----|----------------------------------------------------------------| | name | string | true | The name of your app.| | pages | array | true | A list of pages in your app, each page will be presented as a separated tab, and will have his own methods and properties. | | baseUrl | string | false | Base url of the api. This will prefix the url of all the api methods defined for all pages. This is normally the domain plus a base path. For example: "https://restool-sample-app.herokuapp.com/api" Note: If different pages use different base urls this should not be used. Instead, you should explicitly define absolute urls for each method. | | requestHeaders | object | false | A list of key-value headers you wish to add to every request we're making. For example: { Authentication: 'SECRET_KEY', 'X-USER-ID': 'USER_ID' }. | | errorMessageDataPath | string[] | false | The path within an error response object to look for an error message. If multiple are provided, each will be tried in order until a message is found. | | unauthorizedRedirectUrl | string | false | Legacy option that takes priority over auth config: URL to redirect to when the API returns a 401 (Unauthorized) error. Use :returnUrl to pass a return location. For example: "/login?return=:returnUrl" | | auth | object | false | Built-in authentication configuration (used only if unauthorizedRedirectUrl is not set). See Auth Config below. | | favicon | string | false | A URL for you app's favicon. | | notificationStyle | string ("banner" | "toast") | false | Controls how notifications (success/error messages) are displayed. "banner" shows a fixed banner within the content area, while "toast" shows floating notifications in the top-center. Default is "toast". | | customStyles | object | false | Custom styles | | customLabels | object | false | Custom labels ⚠️ Deprecated. Use i18n language files instead. See Internationalization (i18n) section. | | customLink | string | false | External Link for navigation item (instead of default page app) |

Dynamic configuration file

RESTool also support dynamic js configuration file. Just replace the config.json file with config.js file with this content:

export default {
  // Content is the same as the json config file
}

NOTE: In case you're using the build folder, the config.js must be placed in the folder /build/static/js.

Auth Config

The auth property allows you to configure authentication endpoints. It has the following properties:

| Property | Type | Required? | Description | Expected Format | |----------------|--------------|-----|----------------------------------------------------------------|----------------| | type | "sessioncookie" \| "jwt" \| "oauth2" \| "basic" | true | The authentication type. Currently only "sessioncookie" is implemented - other types will throw an error. | - | | loginEndpoint | string | true | The endpoint to send the login request to. If the response header 'X-Change-Password' is set to 'true', the user will be redirected to the change password page. | Request: POST { username: string, password: string } Response: 200 OK with optional X-Change-Password: true header | | logoutEndpoint | string | true | The endpoint to send the logout request to. | Request: POST Response: 200 OK | | userEndpoint | string | true | The endpoint to get the user data from. It should return a JSON object with the property username. | Request: GET Response: { username: string } | | changePasswordEndpoint | string | true | The endpoint to send password change requests to. | Request: PUT { oldPassword: string, newPassword: string } Response: 200 OK | | icons | object | false | Optional configuration for UI icons. Contains changePassword and logout properties that accept Font Awesome icon names. When not defined for an action, no icon will be shown. | Example: { changePassword: "retweet", logout: "sign-out" } |

Example auth configuration:

{
  "auth": {
    "type": "sessioncookie",
    "loginEndpoint": "/auth/login",
    "logoutEndpoint": "/auth/logout",
    "userEndpoint": "/auth/user",
    "changePasswordEndpoint": "/auth/change-password"
  }
}

Authentication Behavior

RESTool provides a configurable authentication system that integrates with your backend API:

Session Cookie Authentication

When using "type": "sessioncookie", the following behavior applies:

Request Handling
- All requests include credentials: 'include' to ensure cookies are sent
- Browser handles cookie management automatically
Authentication State
- RESTool verifies authentication by calling the configured userEndpoint
- The endpoint must return a user object containing at least { username: string }
Login Flow
- When any request returns 401 Unauthorized, RESTool displays the login form
- After successful login, the original request is retried
Password Change Flow
- If login response includes x-password-change: true header
- User is redirected to password change form
- After successful change, returns to original destination

Pages

Each page is an object and represents a resource in your API. It should have the following properties:

| Property | Type | Required? | Description | |----------------|--------------|-----|----------------------------------------------------------------| | name | string | true | The name of the page. This will be presented in the menu. For translation support, it's recommended to leave this empty and define it in the page's and field's namespace instead. See Internationalization (i18n) section. | | id | string | true | A unique identifier for the page. RESTool will use it to navigate between pages. | | description | string | false | A short description about the page and its usage. For translation support, it's recommended to leave this empty and define it in under the page's and field's namespace instead. See Internationalization (i18n) section. | | icon | string | false | Font Awesome icon name (without the 'fa-' prefix) to display next to the page n

RESTool

Install / Use

README