User interface sketch

2018-02-12 - Future - Tony Finch

The current IP Register user interface closely follows the database schema: you choose an object type (i.e. a table) and then you can perform whatever search/create/update/delete operations you want. This is annoying when I am looking for an object and I don't know its type, so I often end up grepping the DNS or the textual database dumps instead.

I want the new user interface to be search-oriented. The best existing example within the UIS is Lookup. The home page is mostly a search box, which takes you to a search results page, which in turn has links to per-object pages, which in turn are thoroughly hyperlinked.

• Search
• Results
• Object
• Search implementation
• Update
• Transaction
• Update implementation
• API examples
• One more thing...

Search

You should be able to search on almost all of the fields in almost all objects with the one search box. It does the job of the various info_for buttons on the old single_ops page and the search actions on the old table_ops page.

The "almost" needs to be a bit deft: for example, it doesn't make sense to match the domain in boxes (etc.) or the mzone in v4_addresses (etc.) since for the typical user a search will match everything, which isn't entirely useful. Instead a match should lead to something useful like an mzone summary page.

Ideas for special search syntax:

• CIDR range - [ 11.22.33.44/24 ]

• arbitrary range - [ 11.22.33.44 - 55.66.77.88 ]

• match in field - [ sysadmin:fanf2 ]

Results

In all cases the search box is repeated at the top of the page to allow you to adjust the search.

• one match - straight to per-object page

• multiple matches - each result needs to be something like an object type and name (and any other primary key fields), plus any other matching fields as a search snippet

• address range - might need a special results layout to do the job of the old range_ops page

Object

A single object's page should do the job of the old table_ops page, i.e. access to all the fields of the corresponding table.

As well as that it should also do the job of the higher-level pages such as box_ops and service_ops, i.e. also display the relevant entries from the joined tables such as v4_address or srv.

The fields should be liberally hyperlinked, typically to a search results page listing related objects, e.g. click on a hostname to list objects related to the same name, click on an email address to list objects mentioning it in the metadata, etc.

Search implementation

All this search functionality relates to the /query API endpoint I briefly mentioned before. I expect it will be most straightforward to make this resource look at the client's Accept: header, so it returns HTML to browsers and JSON to API clients. (That is, not trying to be a heavy JavaScript single-page app.)

I'm currently not sure if it makes sense to include the hyperlinks in the JSON version. That would suggest a greater intention to use HATEOAS than is actually the case, because the /update endpoint is definitely not RESTful.

Update

As on the old UI, on a per-object page you should be able to:

• delete it
• modify it
• rename it
• create a new object based on editing this one

On the existing UI, objects are displayed in an editable form, but that doesn't allow for hyperlinking, so the new UI will have to be more like Lookup where you have to press a button to switch to edit mode.

It would be nice to be able to infer your intent from which fields you edit. Perhaps, if you edit nothing, you can delete; if you edit anything except the primary key, you are modifying; if you edit only the primary key, you are renaming; if you edit both, you are creating a new object. Dunno if this will be simpler or more confusing - at least,the button will need to change to make the action clear.

The new UI also needs a way to:

• create an objects from scratch

This is more directly discoverable than clone-and-hack, and there might not be a relevant object to clone. This might be a separate tab on a full-fat Project Light page, or a top-right link in Lookup's Lite Light version.

After hitting the update button, you are returned to the object's page for a successful create/modify/rename; for an error or a delete, you are returned to the edit page so you can either correct the error or re-create the deleted object.

Transaction

You should be able to perform any of the five kinds of update either immediately, or add the change to your pending transaction. Maybe the easiest way to indicate this is with a tickybox next to the update button.

In this case you are taken to the pending transaction page, which lists the actions, and any warnings if they will not be able to complete successfully.

On this page you should be able to remove actions from the transaction, and commit it.

The pending transaction page should be another tab alongside the create object tab on a full-fat Project Light page; they should be top-right links in Lookup's Lite Light version.

Update implementation

The /update API endpoint I described before is OK if you allow JavaScript in the browser; the Project Light style basically requires JavaScript already so this is not an awkward additional requirement.

Some edit features are best done with some in-browser code - the DWIM button I mentioned above; editing arbitrary JSON object metadata; and adjusting the form to match the selected type of a new object.

API examples

The /query endpoint will return either HTML UI responses or and JSON API responses, but the query strings will have the same meaning in both cases. The query string will be easily visible to developers in the URL.

For /update the API will be not so easily visible. It would be a good idea to add an advanced mode that shows the API requests and responses, to help developers find out how to perform specific actions from their own manual example.

One more thing...

No more raw Oracle error messages!