[Tools-arch] Recommendation 6: Architectural model for clients

[Jay Daley <[e-mail]>]

=  Recommendation

Recommendation 6:  This survey has identified four broad categories of client that are in use: Editor, Build System, Web Service and Command Line Tool; and four broad categories of functionality provided by the tools: Editing, Boilerplate, Validation and Format Conversion.  An architectural model is needed that sits above and incorporates these categories of clients and functionality, and determines how new and existing services/tools integrate, easily and efficiently. 

=  Commentary

Respondents have been clear that they use the tools from a variety of clients and the current de facto interoperability model is the filesystem.  

	• Editors directly invoke tools locally by pushing the edited content to a temporary file and then reading in the results

	• Build systems invoke multiple tools sequentially passing the output from one to another using a filesystem

	• Using a web service as an interactive UI to a tool with the document provided as input

	• Direct invocation front the command line on a local document.

If these categories of clients are explicitly recognised and put on an equal footing then this leads to a big question:

Should our tools development adopt a modern paradigm for supporting a variety of clients doing the same thing, which is a single backend API with different front ends all calling that same API?

If that is to be the case then it is worthwhile considering standardising aspects of those APIs so that new tools authors do not have to start from scratch and so that clients do not need to support too many different APIs.  Such standardisation might include:

	• The expected action of the tools
		• Editing - alter the existing document/fragment
		• Boilerplate - insert into an existing document/fragment
		• Validation - make no changes to the existing document/fragment but provide a set of annotations of it
		• Format conversion - provide an entirely new document/fragment
	• Fragment identification, selection, annotation etc.

This could come under a single architectural model such as::

        Clients                            API Services      
                                                            
┌──────────────────────┐             ┌──────────────────────┐
│                      │             │                      │
│                      │             │   ┌──────────────┐   │
│                      ├────────────▶│   │   Extract    │   │
│                      │             │   │   Elements   │   │
│   ┌──────────────┐   │             │   └──────────────┘   │
│   │    Editor    │   │             │   ┌──────────────┐   │
│   │              │   │             │   │   Insert     │   │
│   └──────────────┘   ├────────────▶│   │   Custom or  │   │
│   ┌──────────────┐   │             │   │ Boilerplate  │   │
│   │    Build     │   │             │   └──────────────┘   │
│   │    System    │   │             │   ┌──────────────┐   │
│   └──────────────┘   │             │   │   Validate   │   │
│   ┌──────────────┐   ├────────────▶│   │   Full or    │   │
│   │     Web      │   │             │   │   Partial    │   │
│   │   Service    │   │             │   └──────────────┘   │
│   └──────────────┘   │             │   ┌──────────────┐   │
│   ┌──────────────┐   │             │   │   Convert    │   │
│   │   Command    │   ├────────────▶│   │   Between    │   │
│   │  Line Tool   │   │             │   │   Formats    │   │
│   └──────────────┘   │             │   └──────────────┘   │
│                      │             │   ┌──────────────┐   │
│                      ├────────────▶│   │  Datatracker │   │
│                      │             │   │  Submission  │   │
│                      │             │   └──────────────┘   │
│                      │             │                      │
└──────────────────────┘             └──────────────────────┘


-- 
Jay Daley
IETF Executive Director
[e-mail]