goFramework
RESTful APIs v7.1

Getting Started

The goFramework provides a RESTful API accessible via HTTP, allowing for the invocation of its services remotely. Use this API for programmatic invocation of app generation services. This is most useful in CI/CD scenarios where code generation is introduced to expedite application development and to seed the tool chain with the core capabilities of an application. This is a great way to jumpstart DevOps. The following examples uses the curl command and assume replacement of with the name or IP address of the server goFramework is running on.

Templatized Tech Stack Packages

To get started, a list of the available TTSPs should be obtained. Parse this list to determine which TTSP to generated code with.

Issue the following curl directive:
curl -XPOST http://:9000/service.action -F input='{"serviceRequestType" : "TechStackPackageList" }'

Output:

field nametypedescription
id number A unique identifier
ownerId number Registered owner of the TTSP. This could be realMethods or an individual who contributed a TTSP that was validated and made available for community usage.
name string Name of the package.
shortname string Limited chars representing the package name.
version string A unique version of the TTSP provided when the TTSP is registered with the goFramework.
packageXML string The entire XML structure of the TTSP definition.

Retrieve Options for a TTSP

Each TTSP has a set of options that can be applied in order to effect not only how the related code is generated, but how it operates.

field nametypedescription
techStackPackageId string ID of a valid TTSP, made available using service call TechStackPackageList.

For TTSP with id of 1, issue the following curl directive: curl -XPOST http://:9000/service.action -F input='{"serviceRequestType" : "TechStackPackageList", "techStackPackageId" : "1" }'

Output (as JSON)
The return value will be an array of option groupings each containing an array of options

field nametypedescription
option.group.name string The name of the option group

For each option.group.name, expect the following output as an array of options:

field namedescription
name Unique of the option with the option group
value The value for the option field. If non-null, the default value is provided.
type The type of the input field. Valid values include input, boolean, select, and password.
selections If the option type is a select, this field will be populated with the list of valid values.
required A true/false field indicating the field is required or not. Defaults to false.

Retrieve Registered Models

Next, retrieve a list of the available models.

Issue the following curl directive:
curl -XPOST http://:9000/service.action -F input='{"serviceRequestType" : "ModelList" }'

Output

field nametypedescription
id number A Uunique identified.
name string Name of the model.
contributor string Who contributed the model to this TTSP instance. A contributor could be realMethods or an individual contributing for community usage.
type string Type options include UML, Ecore, POJO, SQL_Script, JSON and Unknown.
description string Details about the model

Generate an App

Input Values

Each RESTful call requires one or more of the following input values:

field nametypeservice usagedescription
techStackPackageId string CreateApp ID of a valid TTSP, made available using service call TechStackPackageList.
accessKey string DeleteApp Returned using service call CreateApp, and required to delete a previous created app.
modelBody JSON CreateApp A JSON structure containing an entity structure of objects, data, and relationships.
databaseName string CreateApp Name of the database to persist application data to.
appName string CreateApp Name to apply to the generated application.
modelId number CreateApp The unique identifier of a loaded model, obtained during service call ModelList. If this empty, the modelBody parameter will be used. Otherwise, this parameter takes precedance.
bundleApp boolean CreateApp A true/false indicator for whether the generated app should be bundled into a single ZIP file. If true, the result will return the URL to download the ZIP file within parameter appArchiveUrl.
useGitHub boolean CreateApp A true/false indicator for whether the generated app should be commited to GitHub.
saveModel boolean CreateApp A true/false indicator for whether a modelBody contents should be saved for future usage.
relationalDBType string CreateApp The type of the database to be used. Although goFramework supports a wider variety of RDMBS types, the following are available via the RESTful API: MySQL, SQLServer, Oracle, and Postgres.
modelType string CreateApp The type of the model provided within the modelBody. The following versions are available: UML, Ecore, POJO, SQL_Script, and JSON.
serviceRequestType string --- The type of the service call to make, with valid values being: CreateApp, DeleteApp, TechStackPackageList, and ModelList.
gitHubParams JSON CreateApp If the userGitHub parameter is true, the values to apply in order to connect to GitHub and commit the generated code. Values include the following strings: userName, password, repository tag (default:latest) and host (default:github.com).
gitHubParams JSON CreateApp If the userGitHub parameter is true, the values to apply in order to connect to GitHub and commit the generated code. Values include the following strings: userName, password, repository tag (default:latest) and host (default:github.com).
appParams JSON CreateApp key value pairings of parameters to apply during application creation. Each TTSP has its own set of options so consult the documentation. Each TTSP has the following input parameters: name, description, companyName, appLogoUrl, companyLogoUrl, author, and version.
saveModelParams JSON CreateApp If the saveModel parameter is true, the following parameters are used to save the model: name, description, company, contributor, email.

Results and Result Codes

Each RESTful call will return a JSON result with the following data:

Results

field nametypedescription
resultCode JsonResultCode See below for result codes
msg string A status message with details concerning the result code.
processingMsg string A more detailed message related to the service call.
creationKey string Unique identifier returned upon the successful execution of application creation. This key is required in order to delete generated application files.
appArchiveUrl string URL of the archive file containing all the generated files.

Upon the return to a service call, Interrogate the results codes to determine if successful. If not successful, the result code should provide guidance on how to proceed.

Result Codes

field namemessage
Success Request executed successfully.
BadInputStructure The json structure within the request is not formed correctly. Check the documentation for the proper format.
BadInputValue The input value is invalid
ModelBodyEmpty The model body is empty. If not using an existing model, a model must be provided in order to create an application.
ModelParseError Parsing of the model caused an error. Make sure the model type matches the form provided.
TechStackPackageList The list of available technology stack packages is .
UnknownDataType The data type declared in the model is unknown and unable to be deduced. Check the documentation for the supported types.
NoAssociationFound Cannot create an association for class and role because no class declaration found by the name of
UnknownTechStackPackage No technology stack package found by the name of . Supported packages are .
UnknownRelationalDbType No database type supported by the provided name. Supported types are .
UnknownModelType No model type supported by the name. Supported types are .
InvalidServiceRequest No service request supported by the name provided. Supported service requests are .
InvalidAccessKey Invalid access key supplied. Re-check the key then ensure it was assigned by realMethods during app creation.
RequestExecutionError A general processing exception occurred while performing service request . [Exception : ].

Retrieved Archived Apps

Issue the following curl directive:
curl -XPOST http://:9000/service.action -F input='{"serviceRequestType" : "ArchivedAppList" }'

Output:

field nametypedescription
id number A unique identifier.
name string Name applied to the archive package.
packageName string The name of the TTSP the archived application is based on.
modelName string The name of the model the archived application is based on.
zippedAppPackageURL string The server based URL location of the zipped archived application package

Delete a Generated App

In order to delete a previously generated app, provide the accessKey returned upon successful execution of the service call.

Issue the following curl directive:
curl -XPOST http://:9000/service.action -F input='{"serviceRequestType" : "DeleteApp", "accessKey" : "\\archive\\demo_test_10102017133755.zip" }'

Full Service Example

The following example includes a model as JSON within the modelBody parameter, uses GitHub to commit the generated code and saves the model for future usage

Issue the following curl directive:
curl -XPOST http://:9000/service.action -F input='{ "techStackPackageId":"3", "modelBody":"{ \"containers\":[{ \"name\":\"OrderSystem\", \"host\":\"localhost\", \"port\":\"4567\", \"classes\":[{ \"name\":\"OrderItem\", \"attributes\":[{ \"name\":\"name\",\"type\":\"String\" },{ \"name\":\"product\",\"type\":\"Product\" } ]},{ \"name\":\"Product\", \"attributes\":[{ \"name\":\"name\",\"type\":\"String\" },{ \"name\":\"sku\",\"type\":\"String\" },{ \"name\":\"price\",\"type\":\"double\" },{ \"name\":\"category\",\"type\":\"Category\" } ]},{ \"name\":\"Category\", \"attributes\":[{ \"name\":\"categoryId\",\"type\":\"String\",\"primarykey\":\"true\" },{ \"name\":\"name\",\"type\":\"String\" }] }] },{ \"name\":\"ShoppingCart\", \"host\":\"localhost\", \"port\":\"4568\", \"classes\":[{ \"name\":\"Cart\", \"attributes\":[{ \"name\":\"capacity\",\"type\":\"String\" }], \"associations\":[{ \"name\":\"products\",\"type\":\"Product\",\"multiplicity\":\"OneToMany\" }] },{ \"name\":\"Product\", \"attributes\":[{ \"name\":\"name\",\"type\":\"String\" },{ \"name\":\"price\",\"type\":\"Double\" }] }] }] }", "databaseName":"fooDbName", "appName":"demo", "bundleApp":true, "useGitHub":true, "relationalDBType:"MySQL", "modelType":"JSON", "serviceRequestType:"CreateApp", "appParams": { "name":"demo_test", "description":"my first app","companyName":"Acme Investments","appLogoUrl":"","companyLogoUrl":"", "author":"dev@acme.com","version":"1.0.0" }, "gitHubParams": { "userName":"GitHubUserName","password":"GitHubPassword","repository":"GitHubRepo","tag :"latest","host":"github.com" }, "saveModel":true, "saveModelParams": { "name":"sample uploaded model","description":"uploaded microservice model","company":"realMethods","contributor":"dev","email":"dev@realmethods.com" } }'