ng-admin: Add an AngularJS admin GUI to any RESTful API

This post was updated on 2014/10/30 to update the installation steps.

Plenty of applications require a backend admin tool. At marmelab, we have built several such interfaces using the Sonata Project (which is great by the way). But a few months ago, we needed a backend admin for a NodeJS/MongoDB project ; we didn't want to create an entire Symfony2+Sonata application just for the backend, so we looked for an alternative solution. This is how the idea of this project was born.

For small projects with a simple domain model, we should have a client-side tool that provides a basic admin backend in no time. How to make a tool that can suit applications built on any server language (PHP, Node.js, Go, etc.) and using any persistence engine (PostgreSQL, MySQL, MongoDB, etc.)? Get rid of the language and storage problems, and simply plug it to one common standard, a RESTful API.

Introducing ng-admin

Based on the simple grammar of REST APIs, we've built an Angular.js script called ng-admin. It manages all CRUD (Create, Retrieve, Update, Delete) operations through a simple web interface based on standard controls (powered by Bootstrap). It supports public and private APIs, and all types of relationships between models (one-to-many, many-to-one, many-to-many).

The initial video is a screencast of ng-admin running on top of a classic Post-Comments-Tags REST service. You can test it online using the ng-admin-demo sandbox to add, edit and delete records, but changes are reset every hour. This example is based on a test API built with json-server.

ng-admin uses a simple configuration file, written in pure JavaScript, to describe the backend. We chose JavaScript over JSON (using the same "code vs configuration" approach as Gulp) in order to get more freedom and be more descriptive. For instance, you can define your own JavaScript functions for some specific points, like collections pagination, or validation of a field in the edition form.

ng-admin requires a simple web server, without any server-side language. It's shipped with an optional basic webserver based on Node.js for easier testing.

We're open-sourcing ng-admin today, under the MIT license.

Using It In Your Projects

If you have already developed a RESTful API, you're just three steps away from having a rich GUI in you browser to enable CRUD actions on your domain model:

• Retrieve the module from bower:

bower install ng-admin --save

• Include it:

<link
  rel="stylesheet"
  href="/path/to/bower_components/ng-admin/build/ng-admin.min.css"
/>
<script
  src="/path/to/bower_components/ng-admin/build/ng-admin.min.js"
  type="text/javascript"
></script>

• Make your application depends on it:

var app = angular.module("myApp", ["ng-admin"]);

Your application should use a ui-view:

<div ui-view></div>

Please refer to the installation instruction for more detail about configuration.

Here is a sample of the configuration file for the application that we used as an example (you can see the full version in the README file).

// Declare a new entity
var tag = new Entity("tags")
  .label("Tags")
  // how many element should be displayed in dashboard ?
  .dashboard(10)
  // define your specific pagination function returning GET parameters
  .pagination(function(page, maxPerPage) {
    return {
      _start: (page - 1) * maxPerPage,
      _end: page * maxPerPage,
    };
  })
  // enable lazyload pagination
  .infinitePagination(true)
  .filterQuery(function(query) {
    return {
      filter: query,
    };
  })
  .addField(
    new Field("id")
      .order(1)
      .label("ID")
      .type("number")
      .identifier(true)
      .edition("read-only")
  )
  .addField(
    new Field("name")
      .order(2)
      .label("Name")
      .edition("editable")
      .validation({
        required: true,
        "max-length": 150,
        validator: function(value) {
          // custom validation function
          return value.indexOf("cat") > -1;
        },
      })
  );

What's Next ?

First, we plan to transform it to be an angular module, so it will be easier to use. Then, we'll probably add more widget types (WYSIWIG, double list drag&drop, ...), make columns sortable, and make it even more configurable. The problem at the moment is that the REST specification is pretty loose, so ng-admin must allow the override of the basic REST syntax to match as many APIs as possible.

I had a lot of fun developing this marmelab pet project together with Emmanuel. We would love get your feedback, and to know what seems more useful to you. So don't hesitate to comment and/or contribute to this beautiful project!

Update 2017/01/27: ng-admin is now in version 1.0, and has a lot to offer. And if you're looking for a React.js version, we've rewritten ng-admin as admin-on-rest, leveraging the power of React, Redux, and Material Design. We took all that we learned during 3 years building the ng-admin framework, and made a better, more powerful, and easier to use library. Be sure to check out admin-on-rest!