More properties are needed to support all relevant KSP data
If a property is not set, it must contain None, not just disappear
The API must be secured using the API token of a user
API token must be generatable in the profile settings
GET
The API can be used to fetch recorded data, similar to the public reports
This data must hold the same information as public reports
POST
The API can be used to provide initial data for the following models:
Intervention
Compensation
Eco-Account
The API can be used to toggle checks and recording on shared data (if the user holds the needed permissions). This way the data provider can easily add new data and directly publish them, which is handy for e.g. old cases which are binding by law for years, already
The API must provide different versioning for future enhancements and changes
For the first release something like /api/v1/... is appropriate
If anywhere in the future the API will be capable of more functions or other important changes, the versioning can be increased like /api/v2/... whilst still supporting v1 for a while
# Status quo
Not implemented.
# ToDo
We need an API for external data providing and requesting:
1. The API needs to be documented transparently, so every developer can easily write an API handler.
1. The API needs to be a GeoJSON format (https://geojson.org/)
1. More properties are needed to support all relevant KSP data
1. If a property is not set, it must contain `None`, not just disappear
1. The API must be secured using the API token of a user
1. API token must be generatable in the profile settings
1. `GET`
1. The API can be used to fetch recorded data, similar to the public reports
1. This data must hold the same information as public reports
1. `POST`
1. The API can be used to provide initial data for the following models:
1. Intervention
1. Compensation
1. Eco-Account
1. The API can be used to toggle checks and recording on shared data (if the user holds the needed permissions). This way the data provider can easily add new data and directly publish them, which is handy for e.g. old cases which are binding by law for years, already
1. The API must provide different versioning for future enhancements and changes
1. For the first release something like `/api/v1/...` is appropriate
1. If anywhere in the future the API will be capable of more functions or other important changes, the versioning can be increased like `/api/v2/...` whilst still supporting v1 for a while
The created User token has to be added to the request header ksptoken.
Example response GET Intervention
GET /api/v1/intervention/97d7cce8-83e9-4043-bc76-317caf983a41
Click to expand
{"type":"MultiPolygon","coordinates":[[[[7.593955993652341,50.36244809879689],[7.592582702636717,50.36023051515941],[7.601766586303708,50.35823186336356],[7.603225708007811,50.3628587510637],[7.599148750305174,50.362557606415464],[7.596273422241207,50.362612360130036],[7.593955993652341,50.36244809879689]]]],"properties":{"id":"97d7cce8-83e9-4043-bc76-317caf983a41","identifier":"EIV-12022-B6XGM9","title":"Tolles Baugebiet","created_on":"2022-01-12T11:37:31.580Z","modified_on":"2022-01-21T14:22:12.335Z","responsible":{"registration_office":{"atom_id":1764986,"long_name":"Stadt Koblenz","short_name":null},"registration_file_number":"123","conservation_office":{"atom_id":710138,"long_name":"ST Koblenz","short_name":"25"},"conservation_file_number":"5664","handler":"Stadt Koblenz"},"legal":{"registration_date":"2021-12-27","binding_date":"2022-01-21","process_type":{"atom_id":626841266,"long_name":"Bebauungsplan","short_name":null},"laws":[{"atom_id":710067,"long_name":"Bauordnung von Rheinland-Pfalz","short_name":"LBauO"}]},"compensations":[{"id":"d68e9874-70c0-41c5-bd05-9dda97d70ac0","identifier":"KOM-12022-W3VTY1","title":"Tolle Kompensation"}],"payments":[{"amount":100.0,"due_on":"2022-01-12","comment":""}],"deductions":[{"id":"f784e131-afb7-4e15-ad57-0b2469f5e967","eco_account":{"id":"3e7acd84-bb67-408d-886e-91004c319f38","identifier":"OEK-12022-TW4ECJ","title":"Tolles Ökokonto"},"surface":1000.0,"intervention":{"id":"97d7cce8-83e9-4043-bc76-317caf983a41","identifier":"EIV-12022-B6XGM9","title":"Tolles Baugebiet"}}]}}
Example response GET Compensation
GET /api/v1/compensation/d68e9874-70c0-41c5-bd05-9dda97d70ac0
Click to expand
{"type":"MultiPolygon","coordinates":[[[[7.477097511291501,50.14218444767971],[7.479243278503415,50.140479182654374],[7.483620643615721,50.14300955409459],[7.482976913452146,50.14405466845533],[7.481346130371092,50.14416467916495],[7.479929924011228,50.143174573669675],[7.47808456420898,50.14232196640389],[7.477097511291501,50.14218444767971]]]],"properties":{"id":"d68e9874-70c0-41c5-bd05-9dda97d70ac0","identifier":"KOM-12022-W3VTY1","title":"Tolle Kompensation","created_on":"2022-01-12T11:38:27.127Z","modified_on":"2022-01-12T11:40:01.278Z","is_cef":false,"is_coherence_keeping":false,"intervention":{"id":"97d7cce8-83e9-4043-bc76-317caf983a41","identifier":"EIV-12022-B6XGM9","title":"Tolles Baugebiet"},"before_states":[{"biotope":{"atom_id":136156,"long_name":"Buchenmischwald mit einheimischen Laubbaumarten","short_name":"AA2"},"surface":1000.0}],"after_states":[{"biotope":{"atom_id":136204,"long_name":"Fichtenwald","short_name":"AJ0"},"surface":1000.0}],"actions":[{"action":{"atom_id":709452,"long_name":"Pflanzung von Einzelbäumen","short_name":null},"amount":1000.0,"unit":"qm","comment":""}],"deadlines":[{"type":"finished","date":"2022-01-31","comment":""}]}}
Example response GET EcoAccount
GET /api/v1/ecoaccount/3e7acd84-bb67-408d-886e-91004c319f38
Click to expand
{"type":"MultiPolygon","coordinates":[[[[7.764930725097654,50.530801443594385],[7.763471603393552,50.52709125717179],[7.761154174804686,50.524581259743805],[7.762441635131831,50.52141629007823],[7.766475677490232,50.51950629189859],[7.770338058471677,50.51868769758818],[7.778749465942381,50.51928800147066],[7.780122756958003,50.52763689111973],[7.775144577026365,50.533965783820754],[7.768535614013667,50.533965783820754],[7.764930725097654,50.530801443594385]]]],"properties":{"id":"3e7acd84-bb67-408d-886e-91004c319f38","identifier":"OEK-12022-TW4ECJ","title":"Tolles Ökokonto","created_on":"2022-01-12T11:41:14.328Z","modified_on":"2022-01-12T11:47:45.303Z","deductable_surface":10000.0,"deductable_surface_available":9000.0,"responsible":{"conservation_office":{"atom_id":710123,"long_name":"LK Ahrweiler","short_name":"10"},"conservation_file_number":"123-TEST","handler":"Landkreis Ahrweiler"},"legal":{"agreement_date":"2022-01-11"},"before_states":[{"biotope":{"atom_id":136155,"long_name":"Eichen-Buchenmischwald","short_name":"AA1"},"surface":10000.0}],"after_states":[{"biotope":{"atom_id":136156,"long_name":"Buchenmischwald mit einheimischen Laubbaumarten","short_name":"AA2"},"surface":10000.0}],"actions":[{"action":{"atom_id":709234,"long_name":"Sonstiges (s. Erläuterungen)","short_name":null},"amount":1.0,"unit":"cm","comment":""}],"deadlines":[],"deductions":[{"id":"f784e131-afb7-4e15-ad57-0b2469f5e967","eco_account":{"id":"3e7acd84-bb67-408d-886e-91004c319f38","identifier":"OEK-12022-TW4ECJ","title":"Tolles Ökokonto"},"surface":1000.0,"intervention":{"id":"97d7cce8-83e9-4043-bc76-317caf983a41","identifier":"EIV-12022-B6XGM9","title":"Tolles Baugebiet"}}]}}
Example response GET EMA
GET /api/v1/ema/f1410071-239e-4615-b7a5-f0780030d42c
Click to expand
{"type":"MultiPolygon","coordinates":[[[[7.845568656921382,50.79829702304368],[7.837371826171871,50.80155187891526],[7.835698127746578,50.805267562209806],[7.841062545776364,50.806623577403386],[7.848916053771969,50.808359219420474],[7.855696678161618,50.807057493952975],[7.854666709899899,50.80423696434001],[7.850461006164548,50.80217570040005],[7.845568656921382,50.79829702304368]]]],"properties":{"id":"f1410071-239e-4615-b7a5-f0780030d42c","identifier":"EMA-12022-5T92V0","title":"Tolles EMA","created_on":"2022-01-13T08:22:36.792Z","modified_on":"2022-01-21T08:06:08.874Z","responsible":{"conservation_office":{"atom_id":710123,"long_name":"LK Ahrweiler","short_name":"10"},"conservation_file_number":"unbekannt","handler":"Firma XY"},"before_states":[{"biotope":{"atom_id":136156,"long_name":"Buchenmischwald mit einheimischen Laubbaumarten","short_name":"AA2"},"surface":1.0}],"after_states":[{"biotope":{"atom_id":136164,"long_name":"Buchen-Eichenmischwald","short_name":"AB1"},"surface":1.0}],"actions":[{"action":{"atom_id":709234,"long_name":"Sonstiges (s. Erläuterungen)","short_name":null},"amount":1.0,"unit":"cm","comment":""}],"deadlines":[]}}
This issue will be closed. Any further extensions to the current v1 (which is still in 'alpha', until first feedback from external developers arrive) will be added on separate issues and branches
This issue will be closed. Any further extensions to the current v1 (which is still in 'alpha', until first feedback from external developers arrive) will be added on separate issues and branches
Status quo
Not implemented.
ToDo
We need an API for external data providing and requesting:
None
, not just disappearGET
POST
/api/v1/...
is appropriate/api/v2/...
whilst still supporting v1 for a whileHeader
The created User token has to be added to the request header
ksptoken
.Example response GET Intervention
GET /api/v1/intervention/97d7cce8-83e9-4043-bc76-317caf983a41
Click to expand
Example response GET Compensation
GET /api/v1/compensation/d68e9874-70c0-41c5-bd05-9dda97d70ac0
Click to expand
Example response GET EcoAccount
GET /api/v1/ecoaccount/3e7acd84-bb67-408d-886e-91004c319f38
Click to expand
Example response GET EMA
GET /api/v1/ema/f1410071-239e-4615-b7a5-f0780030d42c
Click to expand
Specification
A german specification has been added here in the wiki
This issue will be closed. Any further extensions to the current v1 (which is still in 'alpha', until first feedback from external developers arrive) will be added on separate issues and branches