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

[Mark Nottingham <[e-mail]>]

Hi Jay,

> On 9 Apr 2021, at 11:12 am, Jay Daley <[e-mail]> wrote:
> 
> =  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. 

I'm not sure 'architectural model' is the right terminology here. What we're seeing is different modes of access to the tools -- I think our goal is to assure that all tools a) are able to be used in each of the modes, and b) get as much leverage/common use out of the provided interfaces as possible (by standardising formats / options / etc.).


> =  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?

I don't understand the use of 'API' here. Are you suggesting that there is some service that runs in the network centrally to provide all tool functions? Or is this an API specific to one programming language?


> 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  │   │
> │                      │             │   └──────────────┘   │
> │                      │             │                      │
> └──────────────────────┘             └──────────────────────┘
> 



--
Mark Nottingham   https://www.mnot.net/