Introducing the Common Gateway - a cutting-edge, advanced technology platform designed to enhance data interaction and exchange for local governments. The Common Gateway is a critical tool for the seamless provision of data to Common Ground services, ensuring smooth, efficient, and secure data transactions.
At its core, the Common Gateway is a plugin-based system, allowing for flexible and customizable operations. It is capable of handling multiple plugins, each with its own unique set of functionalities, encapsulated in the form of installation.json files. The platform comes with a robust Installation Service that can read these installation.json files, understand the plugin\'s requirements, and create basic schema\'s accordingly.
But the Common Gateway is more than just a tool for data exchange. It\'s a comprehensive solution designed to handle a multitude of request types and generate appropriate responses. Whether it\'s an HTTP GET, PUT, POST, or a user downloading a file, the Gateway is equipped to handle it all. It identifies the endpoint, processes the request, and generates an appropriate response, ensuring that any incoming request can be accurately interpreted and handled.
Moreover, the Gateway follows an API-first approach, developing APIs that are consistent and reusable. It also follows the principles of Role-Based Access Control (RBAC), granting permissions to users and applications based on their roles. This ensures a secure and controlled environment for data exchange.
This is a transformative approach to data management, enabling governments to maintain control over their own data while allowing for efficient communication with Common Ground services. It\'s not just about data exchange, but also about creating an ecosystem where information is democratized, access is broadened, and operations are streamlined.
The Common Gateway is built with the future in mind, designed to adapt and grow with the needs of local governments and the communities they serve. It brings the power of data exchange to your fingertips, providing a platform that is as intuitive as it is powerful.
Embrace the future of data exchange with Common Gateway. It\'s time to revolutionize the way your local government handles data, enhancing efficiency, security, and adaptability. With the Common Gateway, you\'re not just preparing for the future, you\'re shaping it.
Documentation
Since documentation for a technical application like the common gateway can be a bit overwhelming, we decided to spread it out in different levels of technical difficulty
(Non-technical) Aimed at product owners and interested parties with no to little technical background: The product page.
(Technical) Aimed at developers want to build plugins or use the gateway as backend: Readme files in the codebase.
(Very technical) Aimed people who want to improve and extend the code base: In code documentations.
If you don\'t like to read documentation online there is also a complete manual available in pdf.
CoreBundle
This repository holds the common-gateway Core Bundle code base. For more information about the Common Gateway project, please visit the Common Gateway Documentation.
WarningThis file is maintained at the Conduction Google Drive. Please make any suggestions of alterations there.
Main Process
The Common Gateway is designed to handle a multitude of request types. Upon receiving a request, the Gateway commences a series of steps to handle the request and provide an appropriate response. The main process is as follows:
Receipt of Request: The Gateway can receive a wide range of request types. These include:HTTP GET, PUT, POST, etc., containing a JSON, XML, or SOAP objectA browser GET request (HTML)A user posting a formA user downloading a file
Endpoint Identification: Once the Gateway receives a request, the first task is to identify the endpoint. The endpoint is a primary determinant of how the request will be processed. Endpoints are mapped to specific functions or services in the Gateway, and the identified endpoint dictates the necessary operations to be performed.
Response Generation: After the request has been processed according to the rules of the identified endpoint, the Gateway generates an appropriate response. This could be a JSON or XML response for API requests, an HTML page for browser requests, or the requested file for download requests.
This main process forms the backbone of the Common Gateway\'s operation. It ensures that any incoming request can be accurately interpreted and handled, and that an appropriate response can be generated and returned to the user.
The use of endpoints allows the Gateway to be highly flexible and adaptable, capable of handling a wide variety of requests and responses, making it an ideal solution for various use cases.
As part of our ongoing efforts to improve and streamline our development process, we\'re transitioning from a single codebase setup to a library-based one. This shift involves migrating code from the existing repository at ConductionNL/commonground-gateway to a new repository at CommonGateway/CoreBundle.
This transition is not just about moving code; it\'s about enhancing the quality of our codebase. We\'re taking this opportunity to clean up both our code and documentation and to increase the coverage of our unit tests. However, this is a significant undertaking, and we\'re not finished yet. As of now, Entities, Controllers, and some workflows, including unit testing, are still located in the old repository. We expect the migration to be completed by summer 2023.
An integral part of this transition is the decoupling of client-specific code from the core codebase. This code will now reside in separate plugin repositories. This separation of concerns ensures a cleaner, more maintainable codebase, and allows for more customizable client implementations.
Please bear with us during this period of transition. We\'re confident that these changes will result in a more robust and efficient gateway, and we appreciate your understanding and patience during this time.
Design Decisions
API First
An API-first approach means that for any given development project, your APIs are treated as "first-class citizens." An API-first approach involves developing APIs that are consistent and reusable, which can be accomplished by using an API description language to establish a contract for how the API is supposed to behave. The specification we use is the OpenAPI Specification. You can view the latest version of this specification (3.0.1) on GitHub.
Documentation
We host technical documentation on Read the Doc\'s and general user information on GitHub pages, to make the documentation compatible with GitHub we document in markdown (instead of reStructuredText). Documentation is part of the project and contained within the /docs folder.
Common Ground
All applications are developed following the Common Ground standards on how a data exchange system should be: modular and open-source. More information on Common Ground can be found here
';
-
-export const endpointContent =
- '
Endpoints
WarningThis file is maintained at the Conduction Google Drive. Please make any suggestions or alterations there.
Endpoints are locations (with addresses) where applications can send and receive messages. The generally consist of a domain and path part together forming an URL. For example in case of thedemo.commongateway.nl/api/pets url, the /api/pets would be the path and and demo.commongateway.nl/ the domain.
The common gateway uses endpoint to allow applications to access it, it splits al endpoints into two categories wich are separated by their first path part.
/admin for endpoints that are part of the gateways internal workings/api for user created endpoints
The regex used by the Gateway to find the endpoint. For the above example, that would be ^pets, but the regex could also allow for variable parts like ^pets/?([a-z0-9-]+)?$. The pathRegex MUST be unique within a Gateway installation
path
no
An array of the items in the path that are separated by / in the endpoint. For the above example that would be [‘pets’,’id’]. Path parts MUST exist of letters and numbers.
pathParts
no
An array containing the parts of the path for setting variables for later processes to use later on. Based on their index in the path array and the variable’s name that should be created. For the above example, that would be [‘1’=>’id’]
methods
no
Determins the HTTP methods suported by this endpoint
An array of the methods that are allowed on this path, for example [‘GET’,’PUT’,’POST’,’PATCH’,’DELETE’]. An endpoint must have at least one method
source
no
Turns the endpoint into a proxy for a differend API
ONE external source that is proxied by the endpoint (see Proxy)
schemas
no
Any schemas provided by the endpoint (see schema’s)
Array of schema\'s
throws
no
Any events thrown by the endpoint (see event-driven)
Array of events thrown when the endpoint is called
Handling incoming traffic
Once an endpoint is called by an external application calls an endpoint(or user, a browser is also an application), the endpoint will handle the following actions in the following order.
As you can see can see there are three basic alternatives
An endpoint is linked to a source (becoming a proxy for that source)
An endpoint is linked to one or more schema\'s
An endpoint is not linked to sources or schema\'s
Note
When a proxy (source) is set on an endpoint the schema fase wil be skipped
Events are always thrown (in all three cases)
If an endpoint is not linked to a source, schema\'s AND dosn\'t contain event it wil always return an error
Proxy
An endpoint MAY be a proxy for another (external) source. In this case, the endpoint will forward all traffic to the external source (and attach authorization if required by that source). It will also pass along:any headers, query parameters, body, and methods (e.g., GET)sent to the endpoint. Keep in mind that it will only do so if the method used is activeated on the endpoint (in practice, it is quite common not to expose delete through an endpoint)
Suppose the endpoint path contains an endpoint parameter in the path regex e.g. example. In that case, it will also forward that message to that specific endpoint on the external source. So gateway.com/api/petstore/pets would be forwarded to petstore.com/pets.
Keep in mind that a proxy does not transform or translate data, it simply forwards the received request to a source and then returns the response of that source. If you require more functionality (e.g. datatransformation or translations) you should setup a schema.
Schema\'s
If an endpoint connects is connected to one or more schemas, it will try to handle the traffic based on the requested service.
Note
If an endpoint is hooked to schema(‘s) it will automatically create an API and appropriate Redoc based on its settings. See API for more information on the API.
It is possible to hook an endpoint to multiple schemas. When hooked to multiple schemas, the endpoint can still handle POST requests, BUT a POST request must include a valid _self.scheme.id or _self. scheme.ref that refersto the appropriate schema so that the endpoint understands what schema you are trying to create.
If an endpoint is hooked to more than one entity, it will render search results from all linked entities based on supplied queries.
GET
POST
PUT
Put request are handled roughly the same as an POST request, with one exception.
On a PUT request an exisiting object wil be entirely replaced by the new object. Values that where present in the original object but are not present in the new object wil be DELETED.
PATCH
Put request are handled roughly the same as an PUT request, with two exception.
On a PATCH request an exisiting object wil be updated by the new object. Values that where present in the original object but are not present in the new object wil be KEPT.
Validity will of the request will be determend afther merging the original and new object. e.g. a required value dosn\'t need to be pressent in an patch request if it was already present in the original object. Assuming that the orignal object already had al required values (or else it could note have been created) a patch requests only required value should be it\'s id (excpetion being that the object definition could have been changed afther the original object was created)
DELETE
Throwing Events
As a final step the endpoint will ALWAYS fire any events that are defined under throws. You can read more about events under events.
When the endpoint throws events, it generates a response in the call cache. After handling all the throws ,are handled it will return the response to the user. The response starts as a 200 OK “your request has been processed”, but may be altered by any action that subscribed to a thrown event may alter it.
Note
Any action can subscribe to an event thrown by an endpoint, but common examples are proxy en request actions. These fulfill the same functionality as the direct proxy or event link but allow additional configuration, such as mapping.
It recomended to ALWAYS fire event asynchronysly
Serialization
Return an error
The endpoint will return an error if no proxy, entities, or throws are defined.
Security
Endpoints MAY be secured by assigning them to user groups. This is done on the basis of methods.
