/ doc / tocInheritance / IP / PConcurrent / BaseController

BaseController

Edit keys at this level only

Edit keys at all sub levels.
NOTE: Edits are always additive. Use 'Invalid' in order to delete keys.

__TOCDet/Assembly = ARCAPI
__TOCDet/Description = Contains basic functionality for serving API methods.0x000D0x000A0x000D0x000ARegarding -ExposingApplicationState-:0x000D0x000AThe specific controller instances serving requests are usually stored in a global -DataStorage- like 'app/0x007BnodeId0x007D/Controller/0x007BTypeOfController0x007D/0x007BControllerId0x007D...'.0x000D0x000A(in other words, -ControllerStorage- actually points to a branch inside -Storage-.)0x000D0x000A0x000D0x000AExamples of API requests and how they are resolved to a Controller by -CatchAll-:0x000D0x000AAPI request URL: https://yourserver.com/RQ/dt/Customer/42 0x000D0x000AController instance (in this case of type -RQController-) to be found in controllerStorage0x005B"RQController"0x005D0x000D0x000AMethod -APIMethod- is called on this instance.0x000D0x000A0x000D0x000AThe following controller classes are included within -ARCAPI-:0x000D0x000A0x000D0x000A-RQController-:0x000D0x000AExecutes a REST like query request against the given -DataStorage-.0x000D0x000AExample: https://yourserver.com/RQ/dt/Customer/42 0x000D0x000A0x000D0x000A-AddController-:0x000D0x000AParses and stores a -PropertyStreamLine-.0x000D0x000AExample: https://yourserver.com/Add/dt/Customer/42/FirstName = John0x000D0x000A0x000D0x000A-GQController-:0x000D0x000AOffers GraphQL queries.0x000D0x000ANot implemented as of Feb 2022.0x000D0x000A0x000D0x000A-EditController-:0x000D0x000AOffers a simple HTML editing environment of the raw -PropertyStream- from the given key.0x000D0x000AExample: https://yourserver.com/Edit/dt/Customer/420x000D0x000A0x000D0x000ANote how these controllers are sufficient for a basic CRUD API (Create, Read, Update, Delete).0x000D0x000A(Delete is done by using the metakey -Invalid-.)0x000D0x000A0x000D0x000AOften no additional -ApplicationSpecificCode- is needed.0x000D0x000A0x000D0x000A-ARCEvent- offers additional controllers of which the most important are -RSController- and -ESController- for operating against the -RegStream- and -EventStream- respectively.0x000D0x000A0x000D0x000ASee -BuildControllerStorage- for how -ApplicationSpecificCode- controllers are integrated.0x000D0x000A0x000D0x000AThis system has the following advantages:0x000D0x000A(Note: The concepts described below has shown little practical value as of Feb 2022).0x000D0x000A0x000D0x000A1) The API-routing syntax is by default exposed to the outside because the -ControllerStorage- is normally inserted into the global -DataStorage-.0x000D0x000ATherefore the standard query mechanism in AgoRapide can be used to get this information by querying like0x000D0x000A'RQ/log/0x005BnodeId0x005D/Controller'0x000D0x000A0x000D0x000A2) The API itself is discoverable even without querying like above, without much special code.0x000D0x000AThis is because an invalid API request is actually analyzed by the same mechanism answering standard queries.0x000D0x000AWhen the error message is returned it actually contains data about the correct syntax.0x000D0x000A0x000D0x000A3) The API is configurable both through the API itself and also over the -PropertyStream-.0x000D0x000AFor instance like 'Add/log/0x005BnodeId0x005D/Controller/RQ/~std/LogLevel = Warning' which would change the log level for the standard instance ('std') of -RQController- to 'Warning'.0x000D0x000A0x000D0x000A4) Different instances of the same controller type can exist and be configured individually.0x000D0x000AFor instance if some specific query needs additional logging down to debug level, a dedicated controller can be created for this and configured individually, like0x000D0x000A'Add/log/0x005BnodeId0x005D/Controller/RQController/~dbg/LogLevel = Debug'0x000D0x000A(Note: Such a debug controller is created by default by -BuildControllerStorage-).0x000D0x000A0x000D0x000ANOTE: Such specific controller instances can be used like 'RQ~dbg/...' instead of 'RQ/~dbg/...'. NOTE: This make inserted links more correct, for instance when -RQController- links to -EditController-0x000D0x000ANOTE: The reason for the somewhat special ~ prefix for the controller instance key is to avoid ambiguities NOTE: which are inherent because the complete hierarchical level has not been deemed necessary to specify explicitly.0x000D0x000A0x000D0x000ASome limitations of this approach are:0x000D0x000A1) Actual API method name is limited to the name of the controller type (without the 'Controller' part).0x000D0x000AThat is, a controller called CustomerController can only serve queries starting with 'Customer'.0x000D0x000A0x000D0x000ANote however that in your -ApplicationSpecificCode- you can implement any additional controllers with routing structure totally independent of this standard generic AgoRapide mechanism.0x000D0x000AIn other words, you can keep the AgoRapide mechanism for its standardised approach to data manipulation and add additional traditional controllers and methods as needed.0x000D0x000A0x000D0x000ANote how the -BaseController- classes (like this class) do not inherit any special Microsoft.AspNetCore.Mvc class. They are totally stand-alone with regard to Microsoft.AspNetCore.Mvc.0x000D0x000A0x000D0x000A
__TOCDet/DocFragType = Class
__TOCDet/Name = BaseController
__TOCDet/Namespace = ARCAPI
__TOCDet/Type = BaseController
__TOCDet/Attribute/AssemblyName = ARCAPI
__TOCDet/Attribute/BaseTypes = PConcurrent
__TOCDet/Attribute/ClassNamespace = ARCAPI
__TOCDet/Attribute/ClassType = BaseController
__TOCDet/Attribute/CorrespondingEnumType = BaseControllerP
__TOCDet/Attribute/Description = Contains basic functionality for serving API methods.0x000D0x000A0x000D0x000ARegarding -ExposingApplicationState-:0x000D0x000AThe specific controller instances serving requests are usually stored in a global -DataStorage- like 'app/0x007BnodeId0x007D/Controller/0x007BTypeOfController0x007D/0x007BControllerId0x007D...'.0x000D0x000A(in other words, -ControllerStorage- actually points to a branch inside -Storage-.)0x000D0x000A0x000D0x000AExamples of API requests and how they are resolved to a Controller by -CatchAll-:0x000D0x000AAPI request URL: https://yourserver.com/RQ/dt/Customer/42 0x000D0x000AController instance (in this case of type -RQController-) to be found in controllerStorage0x005B"RQController"0x005D0x000D0x000AMethod -APIMethod- is called on this instance.0x000D0x000A0x000D0x000AThe following controller classes are included within -ARCAPI-:0x000D0x000A0x000D0x000A-RQController-:0x000D0x000AExecutes a REST like query request against the given -DataStorage-.0x000D0x000AExample: https://yourserver.com/RQ/dt/Customer/42 0x000D0x000A0x000D0x000A-AddController-:0x000D0x000AParses and stores a -PropertyStreamLine-.0x000D0x000AExample: https://yourserver.com/Add/dt/Customer/42/FirstName = John0x000D0x000A0x000D0x000A-GQController-:0x000D0x000AOffers GraphQL queries.0x000D0x000ANot implemented as of Feb 2022.0x000D0x000A0x000D0x000A-EditController-:0x000D0x000AOffers a simple HTML editing environment of the raw -PropertyStream- from the given key.0x000D0x000AExample: https://yourserver.com/Edit/dt/Customer/420x000D0x000A0x000D0x000ANote how these controllers are sufficient for a basic CRUD API (Create, Read, Update, Delete).0x000D0x000A(Delete is done by using the metakey -Invalid-.)0x000D0x000A0x000D0x000AOften no additional -ApplicationSpecificCode- is needed.0x000D0x000A0x000D0x000A-ARCEvent- offers additional controllers of which the most important are -RSController- and -ESController- for operating against the -RegStream- and -EventStream- respectively.0x000D0x000A0x000D0x000ASee -BuildControllerStorage- for how -ApplicationSpecificCode- controllers are integrated.0x000D0x000A0x000D0x000AThis system has the following advantages:0x000D0x000A(Note: The concepts described below has shown little practical value as of Feb 2022).0x000D0x000A0x000D0x000A1) The API-routing syntax is by default exposed to the outside because the -ControllerStorage- is normally inserted into the global -DataStorage-.0x000D0x000ATherefore the standard query mechanism in AgoRapide can be used to get this information by querying like0x000D0x000A'RQ/log/0x005BnodeId0x005D/Controller'0x000D0x000A0x000D0x000A2) The API itself is discoverable even without querying like above, without much special code.0x000D0x000AThis is because an invalid API request is actually analyzed by the same mechanism answering standard queries.0x000D0x000AWhen the error message is returned it actually contains data about the correct syntax.0x000D0x000A0x000D0x000A3) The API is configurable both through the API itself and also over the -PropertyStream-.0x000D0x000AFor instance like 'Add/log/0x005BnodeId0x005D/Controller/RQ/~std/LogLevel = Warning' which would change the log level for the standard instance ('std') of -RQController- to 'Warning'.0x000D0x000A0x000D0x000A4) Different instances of the same controller type can exist and be configured individually.0x000D0x000AFor instance if some specific query needs additional logging down to debug level, a dedicated controller can be created for this and configured individually, like0x000D0x000A'Add/log/0x005BnodeId0x005D/Controller/RQController/~dbg/LogLevel = Debug'0x000D0x000A(Note: Such a debug controller is created by default by -BuildControllerStorage-).0x000D0x000A0x000D0x000ANOTE: Such specific controller instances can be used like 'RQ~dbg/...' instead of 'RQ/~dbg/...'. NOTE: This make inserted links more correct, for instance when -RQController- links to -EditController-0x000D0x000ANOTE: The reason for the somewhat special ~ prefix for the controller instance key is to avoid ambiguities NOTE: which are inherent because the complete hierarchical level has not been deemed necessary to specify explicitly.0x000D0x000A0x000D0x000ASome limitations of this approach are:0x000D0x000A1) Actual API method name is limited to the name of the controller type (without the 'Controller' part).0x000D0x000AThat is, a controller called CustomerController can only serve queries starting with 'Customer'.0x000D0x000A0x000D0x000ANote however that in your -ApplicationSpecificCode- you can implement any additional controllers with routing structure totally independent of this standard generic AgoRapide mechanism.0x000D0x000AIn other words, you can keep the AgoRapide mechanism for its standardised approach to data manipulation and add additional traditional controllers and methods as needed.0x000D0x000A0x000D0x000ANote how the -BaseController- classes (like this class) do not inherit any special Microsoft.AspNetCore.Mvc class. They are totally stand-alone with regard to Microsoft.AspNetCore.Mvc.0x000D0x000A0x000D0x000A
__TOCDet/Attribute/Interfaces = IP0x003BIEnumerable0xoooo003CIKIP0xoooo003E0x003BIEnumerable
__TOCDet/Attribute/SubTypes = AddController0x003BEditController0x003BGQController0x003BRQController
AddController/__TOCDet/Assembly = ARCAPI
AddController/__TOCDet/Description = Parses and stores a -PropertyStreamLine-.0x000D0x000AExample: https://yourserver.com/Add/dt/Customer/42/FirstName = John0x000D0x000A0x000D0x000ASends to -ExternalReceiver- if given.0x000D0x000AAdds to the given -DataStorage- unless -DoNotStoreInternally- is specified.0x000D0x000A0x000D0x000ABulk addition of data:0x000D0x000AIf HTTP POST is used and the parameter postData is given, then it will be treated as a collection of -PropertyStreamLine-s, to which the original request will be prepended for every line.0x000D0x000AExample:0x000D0x000AIf request is 'Add/Customer/42' and postData is the following two lines0x000D0x000A  FirstName = John0x000D0x000A  LastName = Smith0x000D0x000Athen it will be treated as two separate requests like0x000D0x000A  Add/Customer/42/FirstName = John0x000D0x000A  Add/Customer/42/LastName = Smith0x000D0x000A0x000D0x000ATODO: Support use of Query for adding values to multiple entities at once.0x000D0x000ATODO: like 'Add/Customer/WHERE FirstName = John/NameEvaluation = NiceName'0x000D0x000A0x000D0x000AHint: You can test input validation by using the inbuilt classes of -ARCDoc-.0x000D0x000A(assuming that the Apple and Orange classes are included in -AllIPDerivedTypes-.)0x000D0x000AExample queries:0x000D0x000Aapi/Add/Apple/1/Colour = Red   // Should succeed0x000D0x000Aapi/Add/Apple/1/Colour = Redd  // Should fail0x000D0x000Aapi/Add/Apple/1/Color = Red    // Does not fail since Apple class accepts any property (it inherits -PRich-).0x000D0x000Aapi/Add/Orange/1/Color = Red    // Sould fail since Orange accepts only Colour and Name (it inherits -PExact-).0x000D0x000A
AddController/__TOCDet/DocFragType = Class
AddController/__TOCDet/Name = AddController
AddController/__TOCDet/Namespace = ARCAPI
AddController/__TOCDet/Type = AddController
AddController/__TOCDet/Attribute/AssemblyName = ARCAPI
AddController/__TOCDet/Attribute/BaseTypes = PConcurrent0x003BBaseController
AddController/__TOCDet/Attribute/ClassNamespace = ARCAPI
AddController/__TOCDet/Attribute/ClassType = AddController
AddController/__TOCDet/Attribute/Description = Parses and stores a -PropertyStreamLine-.0x000D0x000AExample: https://yourserver.com/Add/dt/Customer/42/FirstName = John0x000D0x000A0x000D0x000ASends to -ExternalReceiver- if given.0x000D0x000AAdds to the given -DataStorage- unless -DoNotStoreInternally- is specified.0x000D0x000A0x000D0x000ABulk addition of data:0x000D0x000AIf HTTP POST is used and the parameter postData is given, then it will be treated as a collection of -PropertyStreamLine-s, to which the original request will be prepended for every line.0x000D0x000AExample:0x000D0x000AIf request is 'Add/Customer/42' and postData is the following two lines0x000D0x000A  FirstName = John0x000D0x000A  LastName = Smith0x000D0x000Athen it will be treated as two separate requests like0x000D0x000A  Add/Customer/42/FirstName = John0x000D0x000A  Add/Customer/42/LastName = Smith0x000D0x000A0x000D0x000ATODO: Support use of Query for adding values to multiple entities at once.0x000D0x000ATODO: like 'Add/Customer/WHERE FirstName = John/NameEvaluation = NiceName'0x000D0x000A0x000D0x000AHint: You can test input validation by using the inbuilt classes of -ARCDoc-.0x000D0x000A(assuming that the Apple and Orange classes are included in -AllIPDerivedTypes-.)0x000D0x000AExample queries:0x000D0x000Aapi/Add/Apple/1/Colour = Red   // Should succeed0x000D0x000Aapi/Add/Apple/1/Colour = Redd  // Should fail0x000D0x000Aapi/Add/Apple/1/Color = Red    // Does not fail since Apple class accepts any property (it inherits -PRich-).0x000D0x000Aapi/Add/Orange/1/Color = Red    // Sould fail since Orange accepts only Colour and Name (it inherits -PExact-).0x000D0x000A
AddController/__TOCDet/Attribute/Interfaces = IP0x003BIEnumerable0xoooo003CIKIP0xoooo003E0x003BIEnumerable
EditController/__TOCDet/Assembly = ARCAPI
EditController/__TOCDet/Description = Offers a simple HTML editing environment of the raw -PropertyStream- from the given key.0x000D0x000AExample: https://yourserver.com/Edit/dt/Customer/420x000D0x000A0x000D0x000AThe HTML form offered will POST directly to -AddController- with the postData-parameter set.0x000D0x000A0x000D0x000ATODO: Note that -JSON- is currently not supported.0x000D0x000ATODO: It might appear to be irrelevant, but it could contain the basic elements for building an HTML editing environment,0x000D0x000ATODO: enabling to client to construct its own HTML page.
EditController/__TOCDet/DocFragType = Class
EditController/__TOCDet/Name = EditController
EditController/__TOCDet/Namespace = ARCAPI
EditController/__TOCDet/Type = EditController
EditController/__TOCDet/Attribute/AssemblyName = ARCAPI
EditController/__TOCDet/Attribute/BaseTypes = PConcurrent0x003BBaseController
EditController/__TOCDet/Attribute/ClassNamespace = ARCAPI
EditController/__TOCDet/Attribute/ClassType = EditController
EditController/__TOCDet/Attribute/Description = Offers a simple HTML editing environment of the raw -PropertyStream- from the given key.0x000D0x000AExample: https://yourserver.com/Edit/dt/Customer/420x000D0x000A0x000D0x000AThe HTML form offered will POST directly to -AddController- with the postData-parameter set.0x000D0x000A0x000D0x000ATODO: Note that -JSON- is currently not supported.0x000D0x000ATODO: It might appear to be irrelevant, but it could contain the basic elements for building an HTML editing environment,0x000D0x000ATODO: enabling to client to construct its own HTML page.
EditController/__TOCDet/Attribute/Interfaces = IP0x003BIEnumerable0xoooo003CIKIP0xoooo003E0x003BIEnumerable
GQController/__TOCDet/Assembly = ARCAPI
GQController/__TOCDet/Description = Offers GraphQL queries.0x000D0x000A0x000D0x000ANot implemented as of Dec 2020.0x000D0x000A
GQController/__TOCDet/DocFragType = Class
GQController/__TOCDet/Name = GQController
GQController/__TOCDet/Namespace = ARCAPI
GQController/__TOCDet/Type = GQController
GQController/__TOCDet/Attribute/AssemblyName = ARCAPI
GQController/__TOCDet/Attribute/BaseTypes = PConcurrent0x003BBaseController
GQController/__TOCDet/Attribute/ClassNamespace = ARCAPI
GQController/__TOCDet/Attribute/ClassType = GQController
GQController/__TOCDet/Attribute/Description = Offers GraphQL queries.0x000D0x000A0x000D0x000ANot implemented as of Dec 2020.0x000D0x000A
GQController/__TOCDet/Attribute/Interfaces = IP0x003BIEnumerable0xoooo003CIKIP0xoooo003E0x003BIEnumerable
RQController/__TOCDet/Assembly = ARCAPI
RQController/__TOCDet/Description = RQ = REST Query. Executes a REST like query request against the given -DataStorage-.0x000D0x000AExample: https://yourserver.com/RQ/dt/Customer/42 0x000D0x000A0x000D0x000AThis class understands two main query-methods, 0x000D0x000A1) Direct key-based into data storage, and0x000D0x000A0x000D0x000A2) -QueryExpression- based.0x000D0x000A0x000D0x000AExamples of 1) Direct key-based into data storage queries:0x000D0x000A'Customer/42' =0x003E Get all the keys for Customer with id 42, but do not get sub-keys.0x000D0x000A'Customer/42/*' =0x003E Get all the keys for Customer with id 42, and also all underlying sub-keys (and their sub-keys and so on).0x000D0x000AAppend query with '.json' in order to get -JSON- (default is -HTML-) .0x000D0x000AFor -HTML- this controller is able to do -LinkInsertionInDocumentation-, presumed that -DocLinks- is set.0x000D0x000A0x000D0x000AExamples of 2) -QueryExpression- based queries.0x000D0x000A'Customer/WHERE FirstName = John/SELECT FirstName, LastName/SKIP 10/TAKE 10'0x000D0x000A(see -QueryExpression- for more examples).0x000D0x000A0x000D0x000A
RQController/__TOCDet/DocFragType = Class
RQController/__TOCDet/Name = RQController
RQController/__TOCDet/Namespace = ARCAPI
RQController/__TOCDet/Type = RQController
RQController/__TOCDet/Attribute/AssemblyName = ARCAPI
RQController/__TOCDet/Attribute/BaseTypes = PConcurrent0x003BBaseController
RQController/__TOCDet/Attribute/ClassNamespace = ARCAPI
RQController/__TOCDet/Attribute/ClassType = RQController
RQController/__TOCDet/Attribute/Description = RQ = REST Query. Executes a REST like query request against the given -DataStorage-.0x000D0x000AExample: https://yourserver.com/RQ/dt/Customer/42 0x000D0x000A0x000D0x000AThis class understands two main query-methods, 0x000D0x000A1) Direct key-based into data storage, and0x000D0x000A0x000D0x000A2) -QueryExpression- based.0x000D0x000A0x000D0x000AExamples of 1) Direct key-based into data storage queries:0x000D0x000A'Customer/42' =0x003E Get all the keys for Customer with id 42, but do not get sub-keys.0x000D0x000A'Customer/42/*' =0x003E Get all the keys for Customer with id 42, and also all underlying sub-keys (and their sub-keys and so on).0x000D0x000AAppend query with '.json' in order to get -JSON- (default is -HTML-) .0x000D0x000AFor -HTML- this controller is able to do -LinkInsertionInDocumentation-, presumed that -DocLinks- is set.0x000D0x000A0x000D0x000AExamples of 2) -QueryExpression- based queries.0x000D0x000A'Customer/WHERE FirstName = John/SELECT FirstName, LastName/SKIP 10/TAKE 10'0x000D0x000A(see -QueryExpression- for more examples).0x000D0x000A0x000D0x000A
RQController/__TOCDet/Attribute/Interfaces = IP0x003BIEnumerable0xoooo003CIKIP0xoooo003E0x003BIEnumerable

Edit single sub keys only: __TOCDet / AddController / EditController / GQController / RQController

Generated 2024-07-03 11:09:37.176 UTC