Merge pull request #2 from christoph-morrison/master
Added markdown version of the german API description
This commit is contained in:
Leon Gaultier
GitHub
commit
a19cd6cdf3
194
docs/API.de.md
Normal file
194
docs/API.de.md
Normal file
@ -0,0 +1,194 @@
|
||||
# API-Beschreibung
|
||||
|
||||
Dieses Dokument beschreibt exemplarisch den Aufbau und die benötigten Rahmenbedingungen eines API Modules für 59_Weather.pm
|
||||
|
||||
Da sich die API selbst noch in Entwicklung befindet, sollte vor jedem neuen API-Module ein Blick in dieses Dokument geworfen werden.
|
||||
|
||||
## Genereller Aufbau des API-Modules
|
||||
|
||||
Das Modul muss zwingend Objektorientiert geschrieben werden. Man sollte sich also schon einmal damit befasst haben um zu verstehen, wie so ein objektorientiertes Modul funktioniert.
|
||||
|
||||
Der Packagename muß im Format `<SERIVCE_NAME>API::Weather` angegeben werden, also z.B.
|
||||
|
||||
package FoobarAPI::Weather
|
||||
|
||||
für den Wetter-Service Foobar.
|
||||
|
||||
## Das Modul
|
||||
|
||||
### Konstruktor
|
||||
|
||||
59_Weather ruft den Konstuktor des API-Moduls wie folgt auf:
|
||||
|
||||
FoobarAPI::Weather->new(
|
||||
{
|
||||
devName => $hash->{NAME},
|
||||
apikey => $hash->{APIKEY},
|
||||
location => $hash->{LOCATION},
|
||||
apioptions => $hash->{APIOPTIONS},
|
||||
language => $hash->{LANG}
|
||||
}
|
||||
);
|
||||
|
||||
Beim Aufruf des Konstruktors wird diesem ein Hash mitübergeben, welcher Listenelemente beinhaltet. (Hash mit Skalaren).
|
||||
|
||||
Jedes Listenelement besteht aus einem Schlüssel und einem Wert. Der Schlüssel muß nicht zwingend in direkter Verbindung zur Bedeutung des Wertes stehen. Der `APIKEY` kann zum Beispiel auch eine Zeichenkette aus der Kombination `Nutzername:Passwort` sein, oder auch ein OAuth-Token. Je nachdem was zum Bezug der Daten vom Anbieter benötigt wird.
|
||||
|
||||
`LOCATION` kann, muss aber nicht, im Format `Latitude,Longitude` angegeben werden, sondern kann auch eine Stations-ID sein. Nur der `devName` muss unbedingt korrekt übergeben und später an die `CallbackFn` zurück gegeben werden.
|
||||
|
||||
Wird `LOCATION` und `LANGUAGE` beim Define des Devices nicht angeben, wird von `Weather` versucht, diese aus dem `global`-Device zu erhalten.
|
||||
|
||||
#### Beispiel
|
||||
|
||||
sub new {
|
||||
### geliefert wird ein Hash
|
||||
my ( $class, $argsRef ) = @_;
|
||||
|
||||
my $self = {
|
||||
devName => $argsRef->{devName},
|
||||
key => $argsRef->{$apikey},
|
||||
cachemaxage => (
|
||||
( defined( $argsRef->{apioptions} ) and $argsRef->{apioptions} )
|
||||
? (
|
||||
( split( ':', $argsRef->{apioptions} ) )[0] eq 'cachemaxage'
|
||||
? ( split( ':', $argsRef->{apioptions} ) )[1]
|
||||
: 900
|
||||
)
|
||||
: 900
|
||||
),
|
||||
lang => $argsRef->{language},
|
||||
lat => ( split( ',', $argsRef->{location} ) )[0],
|
||||
long => ( split( ',', $argsRef->{location} ) )[1],
|
||||
fetchTime => 0,
|
||||
};
|
||||
|
||||
bless $self, $class;
|
||||
return $self;
|
||||
}
|
||||
|
||||
### Verpflichtende Objektmethoden
|
||||
|
||||
Es müssen zwingend zwei Objektmethoden vorhanden sein. `Weather` wird dann über den Konstruktor eine neue Instanz als Instanzvariable anlegen. Über diese Instanzvariablen werden dann die zwei Methodenaufrufe durchgeführt.
|
||||
|
||||
`$obj→setRetrieveData` wird in `Weather` in der GetUpdate-Funktion aufgerufen.
|
||||
|
||||
`$obj→getWeather` wird in der `CallbackFn-Funktion aufgerufen um die Daten aus dem API-Modul zu erhalten. Vorher muss aus dem API-Modul heraus die `CallbackFn` aufgerufen und der Name der `Weather`-Instanz übergeben werden: `Weather_CallbackFn(devName);`
|
||||
|
||||
Für beide Methodenaufrufe **muss** eine entsprechende Methode existieren. Das ist Pflicht.
|
||||
|
||||
### Aufbau der Response des API-Moduls
|
||||
|
||||
Zwingend als Reading müssen folgende Werte geliefert werden, da diese gesondert behandelt werden:
|
||||
|
||||
* `status` (Hash)
|
||||
* `apiMaintainer` (Hash)
|
||||
* `apiVersion` (Hash)
|
||||
* `{license}->{text}` (Hash in Hash)
|
||||
* `{license}->{text}` (Hash in Hash)
|
||||
* `{current}->{code}` (Hash in Hash)
|
||||
* `{current}->{wind_direction}` (Hash in Hash)
|
||||
* `{current}->{wind_speed}` (Hash in Hash)
|
||||
* `{current}->{temperature}` (Hash in Hash)
|
||||
* `{current}->pressure}` (Hash in Hash)
|
||||
* `{current}->{wind}` (Hash in Hash)
|
||||
* `{current}->{humidity}` (Hash in Hash)
|
||||
|
||||
Als Reading empfohlen, da historisch vorhanden und in der Weblink-Ansicht vorhanden:
|
||||
|
||||
* day_of_week (Hash aus forecast)
|
||||
* icon (Hash)
|
||||
* condition (Hash)
|
||||
* temp_c
|
||||
* humidity
|
||||
* low_c
|
||||
* high_c
|
||||
|
||||
#### Beispiel erfolgreiche Datenübertragung
|
||||
|
||||
$response = (
|
||||
{
|
||||
status => 'ok',
|
||||
validity => 'up-to-date',
|
||||
lat => latitude,
|
||||
long => longitude,
|
||||
apiMaintainer => 'Maintainer Info',
|
||||
apiVersion => '2.0.3',
|
||||
current_date_time => am besten die fetchtime,
|
||||
timezone = timezone der Responsedaten,
|
||||
license => {
|
||||
text => 'Lizenz vom Anbieter',
|
||||
},
|
||||
current => {
|
||||
temperature => temperatur vom Anbieter,
|
||||
temp_c => temperatur vom Anbieter,
|
||||
humidity => Luftfeuchte vom Anbieter,
|
||||
condition => Wetterbeschreibung vom Anbieter,
|
||||
},
|
||||
forecast => {
|
||||
daily => [
|
||||
{
|
||||
temperature => temperatur vom Anbieter,
|
||||
temp_c => temperatur vom Anbieter,
|
||||
low_c => niedrigste Temperatur,
|
||||
high_c => höchste Temperatur,
|
||||
},
|
||||
{
|
||||
temperature => temperatur vom Anbieter,
|
||||
temp_c => temperatur vom Anbieter,
|
||||
low_c => niedrigste Temperatur,
|
||||
high_c => höchste Temperatur,
|
||||
},
|
||||
{
|
||||
temperature => temperatur vom Anbieter,
|
||||
temp_c => temperatur vom Anbieter,
|
||||
low_c => niedrigste Temperatur,
|
||||
high_c => höchste Temperatur,
|
||||
},
|
||||
],
|
||||
hourly => [
|
||||
{
|
||||
temperature => temperatur vom Anbieter,
|
||||
temp_c => temperatur vom Anbieter,
|
||||
low_c => niedrigste Temperatur,
|
||||
high_c => höchste Temperatur,
|
||||
},
|
||||
{
|
||||
temperature => temperatur vom Anbieter,
|
||||
temp_c => temperatur vom Anbieter,
|
||||
low_c => niedrigste Temperatur,
|
||||
high_c => höchste Temperatur,
|
||||
},
|
||||
{
|
||||
temperature => temperatur vom Anbieter,
|
||||
temp_c => temperatur vom Anbieter,
|
||||
low_c => niedrigste Temperatur,
|
||||
high_c => höchste Temperatur,
|
||||
},
|
||||
],
|
||||
},
|
||||
);
|
||||
|
||||
#### Beispiel einer fehlerhaften Datenübertragung
|
||||
|
||||
$hash = (
|
||||
{
|
||||
status => $error,
|
||||
validity => 'stale',
|
||||
lat => latitude,
|
||||
long => longitude,
|
||||
apiMaintainer => 'Maintainer Info',
|
||||
current_date_time => x # Die letzte fetchtime einer erfolgreichen Datenabfrage,
|
||||
license => {
|
||||
text => 'Lizenz vom Anbieter',
|
||||
},
|
||||
},
|
||||
);
|
||||
|
||||
Sobald alle Daten fertig verarbeitet wurden und zur Abholung bereit sind, kann das API-Modul die `CallbackFn` von `Weather` aufrufen.
|
||||
|
||||
main::Weather_RetrieveCallbackFn( $self->{devName} );
|
||||
|
||||
Diese Callback-Funktion holt sich dann über den Methodenaufruf `getWeather` die Datenstruktur `$obj->getWeather` und verarbeitet diese in Readings.
|
||||
|
||||
#### Yahoo-API
|
||||
Für das Reading `code` sollte ein Mapping auf die Yahoo-Codes innerhalb des API-Modules stattfinden. Diese findet man in der [Dokumentation der Yahoo API](https://developer.yahoo.com/weather/documentation.html#codes).
|
||||
Loading…
x
Reference in New Issue
Block a user