#Design Considerations
This component was designed inline with the NL API Strategie and https://www.noraonline.nl/wiki/Standaarden.
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 routin. E.g. a propper domain for the production API of the verzoeken registratie component would be api.vrc.zaakonline.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 als assume that you are using your enviroment as a namespace
Symfony libary managment gies 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
- client (An react client frontend)
- admin ( An read admin interface)
If no enviroment is supplied to the load balancer then trafic is routed to the client interface.
We inherit a couple of headers from the transaction logging within the NLX schema, there does however see to be on ongoing discussion on how headers are supposed to be interpreted. The NLX schema states
The outway appends a globally unique
X-NLX-Request-Idto make a request traceable through the network. All the headers are logged before the request leaves the outway. Then the fieldsX-NLX-Request-User-Id,X-NLX-Request-Application-Id, andX-NLX-Request-Subject-Identifierare stripped of and the request is forwarded to the inway*
This would sugjest that no X-NLX-Request-User-Id should be present on an endpoint (since it would have been stripped before getting there) but a X-NLX-Request-Id should be present. If we look at the open case API however exactly the opposite has been implemented. Also a new header X-Audit-Toelichting has been implemented that seems to be doing what X-NLX-Request-Process-Id is doing in the case of a known process
solution
All X-NLX headers are implemented for logging right now, and X-Audit-Toelichting 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 (in stead 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 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.
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 | ||||