GitHub - bfpi/klarschiff-citysdk: Implementation of CitySDK-Smart-Participation-API for Klarschiff

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
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.

Name		Name	Last commit message	Last commit date
Latest commit History 168 Commits
app		app
bin		bin
config		config
db		db
lib		lib
public		public
vendor/assets		vendor/assets
.gitignore		.gitignore
.ruby-gemset		.ruby-gemset
.ruby-version		.ruby-version
Gemfile		Gemfile
Gemfile.lock		Gemfile.lock
LICENSE		LICENSE
Passengerfile.json		Passengerfile.json
README.md		README.md
Rakefile		Rakefile
config.ru		config.ru

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Klarschiff-CitySDK

Supported Response Formats

API Methods

GET Services (List)

Get Service Definition

Get Service Requests (List)

Get Service Request

Create Service Request

Update Service Request

Get Comments from Service Request (List)

Create new Comment for Service Request

Get Notes from Service Request (List)

Create new Note for Service Request

Create new Abuse for Service Request

Create new Vote for Service Request

Create new Photo for Service Request

Get Position Coverage

Get observable Areas

Create new Observation

Get Jobs

Create new Job

Update Job

Installation

Voraussetzungen

Vorbereitungen

Konfiguration der Applikation (Anpassung an die entsprechende Umgebung)

Konfigurationen in der config/settings.yml

Konfigurationen in der config/clients.yml

Konfigurationen in der config/secrets.yml

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Uh oh!

Contributors

Uh oh!

Languages

Konfigurationen in der `config/settings.yml`

Konfigurationen in der `config/clients.yml`

Konfigurationen in der `config/secrets.yml`