Skip to content
This repository was archived by the owner on Dec 14, 2022. It is now read-only.
/ klarschiff-citysdk Public archive

Implementation of CitySDK-Smart-Participation-API for Klarschiff

License

GPL-2.0 license
2 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

bfpi/klarschiff-citysdk

BranchesTags

Repository files navigation

Klarschiff-CitySDK

Implementation of CitySDK-Smart-Participation-API for Klarschiff

This project got superseeded by the new Klarschiff-Backoffice. All known API features are implemented within the new application. The maintenance and support for this repository was stopped. Please migrate to the new Klarschiff-Backoffice.

Supported Response Formats

JSON, XML

API Methods

GET Services (List)

http://[API endpoint]/services.[format]

HTTP Method: GET

Parameters:

Name Required Type Notes
api_key - String API-Key

Sample Response:

<services type="array">
  <service>
    <service_code>category.id</service_code>
    <service_name>category.name</service_name>
    <description/>
    <metadata>false</metadata>
    <type>realtime</type>
    <keywords>category.parent.typ [problem|idee|tipp]</keywords>
    <group>category.parent.name</group>
  </service>
</services>

Get Service Definition

http://[API endpoint]/services/[service_id].[format]

HTTP Method: GET

Parameters:

Name Required Type Notes
api_key - String API-Key
service_id X Integer

Sample Response:

<service_definition type="array">
  <service>
    <service_code>category.id</service_code>
    <service_name>category.name</service_name>
    <keywords>category.parent.typ [problem|idee|tipp]</keywords>
    <group>category.parent.name</group>
  </service>
</service_definition>

Get Service Requests (List)

http://[API endpoint]/requests.[format]

HTTP Method: GET

Parameters:

Name Required Type Notes
api_key - String API-Key
service_request_id - Integer List of multiple Request-IDs, comma delimited
service_code - Integer
status - String Options: default=open, closed
detailed_status - String Options: PENDING, RECEIVED, IN_PROCESS, PROCESSED, REJECTED
start_date - Date e.g 2011-01-01T00:00:00Z
end_date - Date e.g 2011-01-01T00:00:00Z
updated_after - Date e.g 2011-01-01T00:00:00Z
updated_before - Date e.g 2011-01-01T00:00:00Z
agency_responsible - String
extensions - Boolean
lat - Double restriction area (lat, long and radius required)
long - Double restriction area (lat, long and radius required)
radius - Double meter - restriction area (lat, long and radius required)
keyword - String Options: problem, idea, tip
with_foto - Boolean Filter: Meldungen mit freigegebenen Fotos
also_archived - Boolean Filter: Auch archivierte Meldungen berücksichtigen
just_count - Boolean Es soll nur die Anzahl der Meldungen zurückgegeben werden
max_requests - Integer Maximum number of requests
observation_key - String MD5-Hash of observed Area
area_code - Integer Area-ID

Sample Response:

<service_requests type="array">
  <request>
    <service_request_id>request.id</service_request_id>
    <status_notes/>
    <status>request.status</status>
    <service_code>request.service.code</service_code>
    <service_name>request.service.name</service_name>
    <description>request.description</description>
    <agency_responsible>request.agency_responsible</agency_responsible>
    <service_notice/>
    <requested_datetime>request.requested_datetime</requested_datetime>
    <updated_datetime>request.updated_datetime</updated_datetime>
    <expected_datetime/>
    <address>request.address</address>
    <adress_id/>
    <lat>request.position.lat</lat>
    <long>request.position.lat</long>
    <media_url/>
    <zipcode/>
  </request>
</service_requests>

Get Service Request

http://[API endpoint]/requests/[service_request_id].[format]

HTTP Method: GET

Parameters:

Name Required Type Notes
service_request_id X Integer
api_key - String API-Key
extensions - Boolean

Sample Response:

<service_requests type="array">
  <request>
    <service_request_id>request.id</service_request_id>
    <status_notes/>
    <status>request.status</status>
    <service_code>request.service.code</service_code>
    <service_name>request.service.name</service_name>
    <description>request.description</description>
    <agency_responsible>request.agency_responsible</agency_responsible>
    <service_notice/>
    <requested_datetime>request.requested_datetime</requested_datetime>
    <updated_datetime>request.updated_datetime</updated_datetime>
    <expected_datetime/>
    <address>request.address</address>
    <adress_id/>
    <lat>request.position.lat</lat>
    <long>request.position.lat</long>
    <media_url/>
    <zipcode/>
    <extended_attributes>
      <detailed_status>request.detailed_status</detailed_status>
      <media_urls>
        <media_url>request.media.url</media_url>
      </media_urls>
      <photo_required>request.photo_required</photo_required>
      <trust>request.trust</trust>
      <votes>request.votes</votes>
    </extended_attributes>
  </request>
</service_requests>

Create Service Request

http://[API endpoint]/requests.[format]

HTTP Method: POST

Parameters:

Name Required Type Notes
api_key X String API-Key
email X String Author-Email
service_code X Integer Category-ID
description X String Description
lat - Float either lat & long or address_string
long - Float either lat & long or address_string
address_string - String either address_string or lat & long
photo_required - Boolean Photo required
media - String Photo (Base64-Encoded-String)
privacy_policy_accepted - Boolean

Sample Response:

<service_requests>
  <request>
    <service_request_id>request.id</service_request_id>
  </request>
</service_requests>

Update Service Request

http://[API endpoint]/requests/[service_request_id].[format]

HTTP Method: PUT / PATCH

Parameters:

Name Required Type Notes
api_key X String API-Key
email X String Author-Email
service_code - Integer Category-ID
description - String Description
lat - Float either lat & long or address_string
long - Float either lat & long or address_string
address_string - String either address_string or lat & long
photo_required - Boolean Photo required
detailed_status - String Status (RECEIVED, IN_PROCESS, PROCESSED, REJECTED)
status_notes - String Status note
priority - Integer Priority
delegation - String Delegation to external role
job_status - Integer Job status
job_priority - Integer Job priority
media - String Photo (Base64-Encoded-String)

Sample Response:

<service_requests type="array">
  <request>
    <service_request_id>request.id</service_request_id>
    <status_notes/>
    <status>request.status</status>
    <service_code>request.service.code</service_code>
    <service_name>request.service.name</service_name>
    <description>request.description</description>
    <agency_responsible>request.agency_responsible</agency_responsible>
    <service_notice/>
    <requested_datetime>request.requested_datetime</requested_datetime>
    <updated_datetime>request.updated_datetime</updated_datetime>
    <expected_datetime/>
    <address>request.address</address>
    <adress_id/>
    <lat>request.position.lat</lat>
    <long>request.position.lat</long>
    <media_url/>
    <zipcode/>
  </request>
</service_requests>

Get Comments from Service Request (List)

http://[API endpoint]/requests/comments/[service_request_id].[format]

HTTP Method: GET

Parameters:

Name Required Type Notes
service_request_id X Integer
api_key X String API-Key

Sample Response:

<comments type="array">
  <comment>
    <id>comment.id</id>
    <jurisdiction_id></jurisdiction_id>
    <comment>comment.text</comment>
    <datetime>comment.datetime</datetime>
    <service_request_id>comment.service_request_id</service_request_id>
  </comment>
</comments>

Create new Comment for Service Request

http://[API endpoint]/requests/comments/[service_request_id].[format]

HTTP Method: POST

Parameters:

Name Required Type Notes
service_request_id X Integer
api_key X String API-Key
author X String
comment X String
privacy_policy_accepted - Boolean

Sample Response:

<comments>
  <comment>
    <id>comment.id</id>
    <jurisdiction_id></jurisdiction_id>
    <comment>comment.text</comment>
    <datetime>comment.datetime</datetime>
    <service_request_id>comment.service_request_id</service_request_id>
  </comment>
</comments>

Get Notes from Service Request (List)

http://[API endpoint]/requests/notes/[service_request_id].[format]

HTTP Method: GET

Parameters:

Name Required Type Notes
service_request_id X Integer
api_key X String API-Key

Sample Response:

<notes type="array">
  <note>
    <jurisdiction_id></jurisdiction_id>
    <comment>note.text</comment>
    <datetime>note.datetime</datetime>
    <service_request_id>note.service_request_id</service_request_id>
    <author>note.author</author>
  </note>
</notes>

Create new Note for Service Request

http://[API endpoint]/requests/notes/[service_request_id].[format]

HTTP Method: POST

Parameters:

Name Required Type Notes
service_request_id X Integer
api_key X String API-Key
author X String
comment X String

Sample Response:

<notes>
  <note>
    <jurisdiction_id></jurisdiction_id>
    <comment>note.text</comment>
    <datetime>note.datetime</datetime>
    <service_request_id>note.service_request_id</service_request_id>
    <author>note.author</author>
  </note>
</notes>

Create new Abuse for Service Request

http://[API endpoint]/requests/abuses/[service_request_id].[format]

HTTP Method: POST

Parameters:

Name Required Type Notes
service_request_id X Integer
author X String
comment X String
privacy_policy_accepted - Boolean

Sample Response:

<abuses>
  <abuse>
    <id>abuse.id</id>
  </abuse>
</abuses>

Create new Vote for Service Request

http://[API endpoint]/requests/votes/[service_request_id].[format]

HTTP Method: POST

Parameters:

Name Required Type Notes
service_request_id X Integer
author X String Author-Email
privacy_policy_accepted - Boolean
status_updates_for_customer - Boolean Über Statusänderungen informieren

Sample Response:

<votes>
  <vote>
    <id>vote.id</id>
  </vote>
</votes>

Create new Photo for Service Request

http://[API endpoint]/requests/photos/[service_request_id].[format]

HTTP Method: POST

Parameters:

Name Required Type Notes
service_request_id X Integer
author X String Author-Email
media X String Photo (Base64-Encoded-String)

Sample Response:

<photos>
  <photo>
    <id>photo.id</id>
  </photo>
</photos>

Get Position Coverage

http://[API endpoint]/coverage.[format]

HTTP Method: GET

Parameters:

Name Required Type Notes
api_key X String API-Key
lat X Float latitude value
long X Float longitude value

Sample Response:

<hash>
  <result type="boolean">false</result>
</hash>

Get observable Areas

http://[API endpoint]/areas.[format]

HTTP Method: GET

Parameters:

Name Required Type Notes
api_key X String API-Key
ids - String
with_districts - Boolean

Sample Response:

<areas>
  <area>
  <id>30</id>
  <name>Biestow</name>
  <grenze>MULTIPOLYGON (((...)))</grenze>
  </area>
  ...
</areas>

Create new Observation

http://[API endpoint]/observations.[format]

HTTP Method: POST

Parameters:

Name Required Type Notes
api_key X String API-Key
geometry * String
area_code * String
problems - Boolean
problem_service - String
problem_service_sub - String
ideas - Boolean
idea_service String
idea_service_sub String

*: Either geometry or area_code is required

Sample Response:

<observation>
  <rss-id>39a855f0a4924af3217a217c8dc78ece</rss-id>
</observatio>

Get Jobs

http://[API endpoint]/jobs.[format]

HTTP Method: GET

Parameters:

Name Required Type Notes
api_key X String API-Key
date X Date Jobs that are the equal or lower than the given date
status - String Status (CHECKED, UNCHECKED, NOT_CHECKABLE)

Sample Response:

<jobs>
  <job>
    <id>job.id</id>
    <service-request-id>job.service_request_id</service-request-id>
    <date>job.date</date>
    <agency-responsible>job.agency_responsible</agency-responsible>
    <status>job.status</status>
  </job>
  ...
</jobs>

Create new Job

http://[API endpoint]/jobs.[format]

HTTP Method: POST

Parameters:

Name Required Type Notes
api_key X String API-Key
service_request_id X Integer
agency_responsible X String
date X Date

Sample Response:

<jobs>
  <job>
    <id>job.id</id>
    <service-request-id>job.service_request_id</service-request-id>
    <date>job.date</date>
    <agency-responsible>job.agency_responsible</agency-responsible>
    <status>job.status</status>
  </job>
</jobs>

Update Job

http://[API endpoint]/jobs/[service_request_id].[format]

HTTP Method: PUT / PATCH

Parameters:

Name Required Type Notes
api_key X String API-Key
status X String Status (CHECKED, UNCHECKED, NOT_CHECKABLE)
date X Date

Sample Response:

<jobs>
  <job>
    <id>job.id</id>
    <service-request-id>job.service_request_id</service-request-id>
    <date>job.date</date>
    <agency-responsible>job.agency_responsible</agency-responsible>
    <status>job.status</status>
  </job>
</jobs>

Installation

Voraussetzungen

  • RVM / oder andere Rubyversionsverwaltung

    • Installation von RVM (kann übersprungen werden wenn diese bereits erfolgt ist):

      \curl -L https://get.rvm.io | sudo bash -s stable --ruby

    • Aktualisierung von RVM (falls es bereits systemweit installiert ist)

      rvmsudo rvm get stable
  • Passenger-Apache-Modul installieren: Hierzu am besten der offiziellen Anleitung unter https://www.phusionpassenger.com/documentation/Users%20guide%20Apache.html#installation folgen.

Vorbereitungen

  • checkout / clone des Repositories in ein lokales Verzeichnis. Z.B.:

    sudo mkdir -p /var/rails
cd /var/rails
git clone https://github.com/bfpi/klarschiff-citysdk.git

  • Installation der notwendigen Rubyversion und des Gemsets

    • Bei Wechsel in das Repository-Verzeichnis hilft RVM mit der Einrichtung

    • Gegebenenfalls muss das entsprechende Ruby installiert werden:

      rvm install ruby-2.3.2

    • Ein erneuter Wechsel in das Verzeichnis legt anschließend die notwendigen Wrapper und das Gemset an

      ruby-2.3.2 - #gemset created /usr/local/rvm/gems/ruby-2.3.2@klarschiff-citysdk_r01
ruby-2.3.2 - #generating klarschiff-citysdk_r01 wrappers................

    • Falls bundler nicht (mehr) als Default-Gem durch RVM installiert wird, kann dies wie folgt nachgeholt werden:

      gem install bundler --no-ri --no-rdoc

    • Zur Installation der Gems für die Anwendung ist im Verzeichnis nun folgender Aufruf notwendig:

      bundle install

    • Precompilieren der Assets (Bilder)

      rake assets:precompile

Konfiguration der Applikation (Anpassung an die entsprechende Umgebung)

Für die Konfigurationsdateien mit vertraulichem Inhalt gibt es versionierbare Vorlagen mit dem Namen xyz.sample.yml. Diese müssen kopiert und entsprechend ohne das sample als xyz.yml benannt werden. Die für die Umgebung gültigen Werte werden dann in der xyz.yml konfiguriert.

Konfigurationen in der config/settings.yml

  • Interne Vorgabewerte werden als Konstanten in dem Block constants konfiguriert.
  • Weitere Blöcke sind bisher nicht implementiert.

Konfigurationen in der config/clients.yml

In dieser Datei erfolgt die Berechtigungsdefinition für die zu unterstützenden API-Clients.

  • Jeder neue Client wird mit einem eigenene API-Key als Schlüssel in dieser Datei eingefügt.
  • Unterhalb dieses Schlüssels können folgende Werte konfiguriert werden:

    • name, ist optional, soll aber für die Verständlichkeit einen Bezeichner des API-Clients tragen können (z.B. Prüf- und Protokoll-Client).

    • backend_auth_code, konfiguriert den Authorisierungsschlüssel für die erweiterte Kommunikation mit dem Backend. Dieser muss mit dem Property-Wert auth.kod_code in der settings.properties im Backend der jeweiligen Zielumgebung übereinstimmen.

    • permissions, definiert die für diesen Client erlaubten Berechtigungen. Die Definition erfolgt als YAML-Array, also ein Eintrag pro Zeile. Die Werte werden als Ruby-Symbol geschrieben. Beispiel:

      permissions:
  - :create_comments
  - :create_notes

Konfigurationen in der config/secrets.yml

Die Datei dient der Konfiguration zur Verschlüsselung der internen Nutzerdaten (Cookies, usw.).

  • Die Konfiguration erfolgt hier nach Rails-Konvention pro Umgebung. Es muss aber nur die Variante mit der entsprechenden Umgebung konfiguriert werden. Also production in der Produktivumgebung und der Demo-Umgebung. Die RAILS_ENV test ist für automatisierte Tests im Framework vorbehalten.

About

Implementation of CitySDK-Smart-Participation-API for Klarschiff

Resources

Readme

License

GPL-2.0 license
Activity
Custom properties

Stars

2 stars

Watchers

6 watching

Forks

0 forks
Report repository

Releases

2 tags

Contributors 6

Languages