This component was designed inline with the NL API Strategie, NORA, vng.cloud, commonground principles and international standards.
The spefic goal of this component is to provide a common architecture for common ground components as such the common ground principles are leading in design choices, and within those principles technological invoation and international complyancy is deemd most inportant. WE DO NOT WANT TO MAKE CONSESIONS TO CURRENT INFRASTRUCTURE. As such the component might differ on NL API Strategie, NORA, vng.cloud and other standards if they are deemed incompatible or out of line with international standards.
By convention the component assumes that you follow the common ground domain name build up, meaning {enviroment}.{component}.{rest of domain}. That means that only the first two url parts are used for routing. It is also assumed that when no envirment is supplied the production enviroment should be offerd E.g. a propper domain for the production API of the verzoeken registratie component would be prod.vrc.zaakonline.nl but it should also be reachable under vrc.zaakonline.nl. The proper location for the development enviroment shoud always be dev.vrc.zaakonlin.nl
We assume that for that you want to run several enviroments for development purposes. We identify the following namespaces for support.
- prod (Production)
- acce (Acceptation)
- stag (Staging)
- test (Testing)
- dev (Development)
Becouse we base the commonground infastructure on kubernetes, and we want to keep a hard sepperation between enviroment we also assume that you are using your enviroment as a namespace
Symfony libary managment gives us the optoin to define the libbarys on a per envirmoent base, you can find that definition in the bundle config
Besides the API envormiments the component also ships with aditional tools/enviroments but those are not meant to be deployed
- client (An react client frontend)
- admin ( An read admin interface)
On the local development docker deploy the client enviroment is used as default in stead of the production version of the api.
@todo update, a reaction about this has been given by the NLX team.
We inherit a couple of headers from the transaction logging within the NLX schema, we strongly discurage the use of the X-NLX-Request-Data-Subject header as it might allow private data (such as BSN's) to show up in logging.
solution
The follwoing X-NLX headers have been implemented X-NLX-Logrecord-ID,X-NLX-Request-Process-Id,X-NLX-Request-Data-Elements and X-NLX-Request-Data-Subject, these are tied to the internal audit trail (see audit trail for more information), and X-Audit-Toelichting (from the ZGW API's) is implemented as X-Audit-Clarification
As per landelijke API-strategie. major versions in endpoint minor versions in header, for this the API-Version is used (instead of the api-version header used in haal centraal)
A part of the haal centraal the concept of field limitations has been introduced its general purpose being to allow an application to limit the returned fields to prevent the unnecessary transportation of (private) data. In the NL API Strategie this has been implemented as a parameter consisting of comma separated values. However the normal web standard for optional lists (conform w3c form standards) is an array.
solution The fields parameter and functionality has been implemented as an array
A part of the [haal centraal](https://raw.githubusercontent.com/VNG-Realisatie/Haal-Centraal-BRP-bevragen/master/api-specificatie/Bevraging-Ingeschreven-Perso on/openapi.yaml) the concept of extending has been introduced, its general purpose being to allow the inclusion of sub resources at an api level thereby preventing unnecessary API calls. In the NL API Strategie this has been implemented as a parameter consisting of comma separated values. However the normal web standard for optional lists (conform w3c form standards) is an array.
solution The extend parameter has been implemented as an array
In line with the extending and fields principle whereby we only want resources that we need it was deemed, nice to make a sub resource of the archivation properties. This also results in a bid cleaner code.
@todo this needs to be implemented For notifications we use the base mechanism as provided by vng.cloud but we differ on insight into the data that should be returned and feel that the international standard RFC 3881 should have been followed here.
solution In compliance with vng.cloud each individual object should support an /audittrail endpoint. You can look into the tutorial for specifications on how to activate an audit trail for a given object. However, instead of the values mention in the vng.cloud design we follow RFC 3881 for the return values. And we give NLX values precedence if provided.
@todo this needs to be implemented For notifications we do not use the current ZGW standard since we deem it insecure to send properties or data objects along with a notification. This is a potential security breach explained here. It also doesn�t follow the web standard. Instead we are developing our own subscriber service that is tailored for the NLX / VNG environment and based on current web standards here.
solution In compliance with w3.org each endpoint returns an header containing an subscribtion url. That can be used in acordanse with the application to subscribe to both individual objects as collections. whereby collections serve as 'kanalen'.
@todo this needs to be implemented We implement user scopes as per vng.cloud standard. But see problems with how the scopes are defined and named, and consider the general setup to be to focused on ZGW (including Dutch naming, zgw specific fields like maxVertrouwlijkheid and a lack of CRUD thinking). There is a further document concerning Authentication and Authorization that details how we should authenticate users and give them scopes. We agree with the principles of the document on application based authorization and the use of JWT tokens. But disagree on some key technical aspect. Most important being that the architecture doesn't take into consideration the use of one component by several organizations
solution No solution as of yet, so there is no implementation of Authorization or Scopes. We might build a new Authorization Component in the long run.
A part of the haal centraal the concept of timetravel has been introduced, as in getting the version of an object as it was on a given date. For this the geldigop see the docs header is used. In addition the geldigvan and geldigtot are introduced as collection filters.
The commonground proto componant natively supports time traveling on all entities that are annotaded with the @Gedmo\Loggable, this is done by adding the ?validOn=[date] query to a request, date can either be a datetime or datedatime string. Any value supported by php's strtotime() is supported. Keep in mind that this returns the entity a as it was valid on that time or better put, the last changed version BEFORE that moment. To get a complete list of all changes on a item the ?showLogs=true quarry can be used.
solution
In compliance with schema.org geldigop,geldigvan and geldigtot are implemented as validOn,validFrom and validUntil. And can be used a query parameters on colelction operations.
Additionally validOn can be used on a single object get request to get the version of that object on a given date, a 404 is returned if no version of that object can be given for that date
In the zaak-api ordering is done in a single field parameter, we however prefer to be able to order on multiple fields in combination of ascending and descending orders. We therefore implement an order parameter as array where they key is the property on wish should be ordered and the value the type of ordering e.g. ?order[name]=desc&order[status]=asc. The order in which the keys are added to the order array determines the order in which they are applied.
The NL API Standard describes that there is a preference for Dutch in API documentation.
Define resources and the underlying entities, fields and so on (the information model ad the external interface) in Dutch. English is allowed in case there is an official English glossary.
We view this as a breach with good coding practice and international coding standards, all documentation is therefore supplied in English
The NL API standard uses comma notation on array's in http requests. E.g. fields=id,name,description however common browsers(based on chromium e.g. chrome and edge) use bracket notation for query style array's e.g. fields[]=id&fields[]=name,&fields[]=description. The difference of course is obvious since comma notation doesn't allow you to index arrays. Interestingly enough there isn't actually a rfc spec for this.
It is perceivable that in future iterations we would like to use indexed array in situations where the index of the array can't be assumed on basis of url notation, when indexes aren�t numerical, when we don�t want an index to start at 0 or when indexes are purpusly missing (comma notation of id,name,description would always refert to the equivalent of fields: [ 0 => id, 1 => name, 2 => description ]
solution We support both comma and bracket notation on array's, but only document bracket notation since it is preferred.
Because it is based on api-platform de proto component supports filter functions as in api platform additionally there are custom filter types available for common ground.
Regex Exact
Regex Contains
Like_ The like filters is used to search for enities with the traditional sql LIKE operator. If pattern does not contain percent signs or underscores, then the pattern only represents the string itself; in that case LIKE acts like the equals operator. An underscore (_) in pattern stands for (matches) any single character; a percent sign (%) matches any sequence of zero or more characters.
Some examples:
'abc' LIKE 'abc' true 'abc' LIKE 'a%' true 'abc' LIKE 'b' true 'abc' LIKE 'c' false LIKE pattern matching always covers the entire string. Therefore, if it's desired to match a sequence anywhere within a string, the pattern must start and end with a percent sign.
To match a literal underscore or percent sign without matching other characters, the respective character in pattern must be preceded by a backlash.
We no longer provide a load balancer per component, since this would require a ip per component. Draining ip's on mult component kubernetes clusters. In stead we make componentes available as an interner service
A component is (speaking in kubernetes terms) a service that is available at
| Period Designator | Description |
|---|---|
| Y | years |
| M | months |
| D | days |
| W | weeks. These get converted into days, so cannot be combined with D. |
| H | hours |
| M | minutes |
| S | seconds |
| Type | Format | Example | Source | Description | Documentation |
|---|---|---|---|---|---|
| integer | int32 | ||||
| integer | int64 | ||||
| string | float | 0.15625 | wikipedia | ||
| string | double | 0.15625 | wikipedia | ||
| integer | byte | ||||
| integer | binary | ||||
| string | date | ||||
| string | date-time | ||||
| string | duration | P23DT23H | wikipedia | ||
| string | password | ||||
| string | boolean | ||||
| string | string | ||||
| string | uuid | ||||
| string | uri | ||||
| string | |||||
| string | rsin | ||||
| string | bag | A BAG uuid | |||
| string | bsn | ||||
| string | iban | ||||