json-idl.md

The desired workflow:

1. service owner design API interfaces using their favourite language

   For example, Jon snow is a groovy developer, he now is in duty of writing a BlackCastle module, he is planning to add an facade API interface LordCommanderFacade.

2. new interface modification commit to a dev branch

   Jon start a new branch on the project git repository. And the new facade API interface is look like following:

    package org.sevenkingdom.blackcastle
   
    /**
     * A lord commander in black castle is the man in charge.
    **/
    @FacadeAPI
    interface LordCommanderFacade {
    	/**
    	 * commands someone to do the action, and take the consequence
    	 * @param whom the command target
    	 * @param voiceCommand the command voice
    	 * @returns the action result
    	 * @throws BetrayalException when the target betrayed the commander
    	**/
    	ConsequenceDTO command(string whom, ActionDTO<VoiceDTO> voiceCommand)
   
    	...
   
    }
   

   DTO defination ommited

3. submit the branch to be reviewed

4. tag the new version of reviewed API

5. commit hook processes the new API version

   1. parse API interface source code to JSON-IDL

   groovy2jsonidl src/org/sevenkingdom/blackcastle
   

   will out put

   {
   	"meta": {},
   	"interfaces": [
   		{
   			"package": "org.sevenkingdom.blackcastle",
   			"name": "LordCommanderFacade",
   			"doc": "A lord commander in black castle is the man in charge.",
   			"meta": [
   				{
   					"type": "org.nofdev.rpc.FacadeAPI",
   					"args": {}
   				},
   			],
   			"methods": [
   				{
   					"name": "command",
   					"doc": "commands someone to do the action, and take the consequence",
   					"throws": [
   						{
   							"type": "org.sevenkingdom.blackcastle.BetrayalException",
   							"doc": "when the target betrayed the commander"
   						}
   					],
   					"return": {
   						"type": "org.sevenkingdom.blackcastle.ConsequenceDTO",
   						"doc": "the action result"
   					},
   					"args": [
   						{
   							"name": "whom",
   							"type": "string",
   							"doc": "the command target"
   						},
   						{
   							"name": "voiceCommand",
   							"type": "org.sevenkingdom.blackcastle.ActionDTO",
   							"typeParams": [
   								"org.sevenkingdom.blackcastle.VoiceDTO"
   							],
   							"doc": "the command voice"
   						}
   					]
   				}
   			]
   		},
   	],
   	"types": [
   		{
   			"package": "org.sevenkingdom.blackcastle",
   			"name": "ActionDTO",
   			"doc": "a command action detail",
   			"meta": {},
   			"properties": [
   				{
   					"name": "...",
   					"type": "...",
   					"doc": "..."
   				}
   			]
   		},
   	],
   }

   1. save this JONS-IDL as a module description file org.sevenkingdom.blackcastle.module.idl.json.
   2. push this file to central API managment console.

   groovy2jsonidl src/org/sevenkingdom/blackcastle | ff soa idl push --group sevenkingdom --project blackcastle --json --file -

   1. the API managment console will generate all language bindings of this API module.

   jsonidl2ts sevenkingdom.blackcastle.module.idl.json
   npm build
   npm push
   
   jsonidl2groovy sevenkingdom.blackcastle.module.idl.json
   gradle publish
   
   jsonidl2csharp sevenkingdom.blackcastle.module.idl.json
   msbuild
   nuget publish

6. and finally, all other project can consume this API module easily.

   npm install --save sevenkingdom-blackcastle

Jobs

Specific language to Json IDL

• Groovy/Java to Json IDL
• C# to json idl
• Typescript to Json IDL

Json IDL to specific language

• Json IDL to Typescript
• Json IDL to Groovy/Java
• Json IDL to C#