API #31

Closed
opened 3 years ago by mpeltriaux · 3 comments
Owner

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.
  2. The API needs to be a GeoJSON format (https://geojson.org/)
    1. More properties are needed to support all relevant KSP data
    2. If a property is not set, it must contain None, not just disappear
  3. The API must be secured using the API token of a user
    1. API token must be generatable in the profile settings
  4. GET
    1. The API can be used to fetch recorded data, similar to the public reports
    2. This data must hold the same information as public reports
  5. POST
    1. The API can be used to provide initial data for the following models:
      1. Intervention
      2. Compensation
      3. Eco-Account
    2. 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
  6. The API must provide different versioning for future enhancements and changes
    1. For the first release something like /api/v1/... is appropriate
    2. 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
mpeltriaux added the
feature
label 3 years ago
mpeltriaux self-assigned this 3 years ago
mpeltriaux added the
enhancement
label 3 years ago
mpeltriaux referenced this issue from a commit 3 years ago
mpeltriaux referenced this issue from a commit 3 years ago
mpeltriaux referenced this issue from a commit 3 years ago
Poster
Owner

Header

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": []
    }
}
# Header 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` <details> <summary>Click to expand</summary> ```json { "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" } } ] } } ``` </details> # Example response GET Compensation ` GET /api/v1/compensation/d68e9874-70c0-41c5-bd05-9dda97d70ac0 ` <details> <summary>Click to expand</summary> ```json { "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": "" } ] } } ``` </details> # Example response GET EcoAccount ` GET /api/v1/ecoaccount/3e7acd84-bb67-408d-886e-91004c319f38 ` <details> <summary>Click to expand</summary> ```json { "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" } } ] } } ``` </details> # Example response GET EMA ` GET /api/v1/ema/f1410071-239e-4615-b7a5-f0780030d42c ` <details> <summary>Click to expand</summary> ```json { "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": [] } } ``` </details>
mpeltriaux referenced this issue from a commit 3 years ago
mpeltriaux referenced this issue from a commit 3 years ago
mpeltriaux referenced this issue from a commit 3 years ago
mpeltriaux referenced this issue from a commit 3 years ago
mpeltriaux referenced this issue from a commit 3 years ago
mpeltriaux referenced this issue from a commit 3 years ago
mpeltriaux referenced this issue from a commit 3 years ago
mpeltriaux referenced this issue from a commit 3 years ago
mpeltriaux referenced this issue from a commit 3 years ago
mpeltriaux referenced this issue from a commit 3 years ago
mpeltriaux referenced this issue from a commit 3 years ago
mpeltriaux referenced this issue from a commit 3 years ago
mpeltriaux referenced this issue from a commit 3 years ago
mpeltriaux referenced this issue from a commit 3 years ago
mpeltriaux referenced this issue from a commit 3 years ago
mpeltriaux referenced this issue from a commit 3 years ago
mpeltriaux referenced this issue from a commit 3 years ago
mpeltriaux referenced this issue from a commit 3 years ago
mpeltriaux referenced this issue from a commit 3 years ago
mpeltriaux referenced this issue from a commit 3 years ago
mpeltriaux referenced this issue from a commit 3 years ago
mpeltriaux referenced this issue from a commit 3 years ago
mpeltriaux referenced this issue from a commit 3 years ago
mpeltriaux referenced this issue from a commit 3 years ago
mpeltriaux referenced this issue from a commit 3 years ago
Poster
Owner

Specification

A german specification has been added here in the wiki

# Specification A german specification has been added [here in the wiki](wiki/api_de)
mpeltriaux referenced this issue from a commit 3 years ago
Poster
Owner

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
mpeltriaux closed this issue 3 years ago
Sign in to join this conversation.
Loading…
There is no content yet.