Specifikáció az API wrapperhez

gplesz commented 5 years ago

Ami az első látásra látszik, hogy a darksky API-t egyszer kell majd meghívni, egy kérésre visszaadja az aktuális időpont előrejelzését és az egyheti előrejelzést is. A következő feladatokkal érdemes lesz foglalkozni:

[x] authentikáció az API kulcsot kér a felhasználó azonosításhoz. Első változatban ez az alkalmazás beállításaiból jön, de érdemes megvizsgálni, hogy lehet-e a kulcsot API-n keresztül elkérni?
[x] a visszatérő adatok meghatározása ez most úgy néz ki, hogy bővebb adathalmaz érkezik, mint amire szükségünk van, így a feladat, exclude paraméterekkel kitiltani a szükségtelen adatokat.
[x] a dokumentáció javasolja nagyobb mennyiségű visszaadott információnál a HTTP tömörítés használatát.
[x] az ingyenes vagy fizetett lekérdezést jelölni, és ezzel együtt az ingyenes napi 1000 lekérdezésből az elhasznált és még rendelkezésre álló mennyiséget jelölni.
[x] az API által visszaadott adatok modelljének a felépítése
[ ] Hibakezelés
- [ ] nincs hálózat
- [ ] nem elérhető az API
- [ ] kifutottunk a rendelkezésre álló keretből

gplesz commented 5 years ago

Az authentikáció a regisztráción alapul, ami egy webes felületet és egy ellenőrző emailt használ, erre nincs API, ha jól láttam. Így a fehasználónak a saját API kulcsát vagy az én API kulcsomat kell használnia, az alkalmazásból most nem fogunk regisztrálni.

gplesz commented 5 years ago

Az adatok lekéréséhez meghatározzuk a hívási paraméteket. Feladatok:

[x] a lekérdezéshez használt koordináták meghatározása mivel fixen megadott városokat kell tudni lekérdezni, így a ezeket fix paraméterként használhatjuk az alkalmazáshoz. Amennyiben kötetlen városok lekérdezését szeretnénk a továbbiakban beépíteni, mivel csak koordinátákat fogad a darksky API, így a cím->koordináta átalakítást külső szolgáltató felé történő hívással tudjuk megodani. A doksi a google és a [mapbox] szolgáltatást ajánlja. A feladatban szereplő városok a következők:
- Budapest: (47.49801, 19.03991)
- Luxembourg: (49.61167, 6.13)
- Debrecen: (47.53333, 21.63333)
- Pécs: (46.08333, 18.23333)
- Wienna: (48.20849, 16.37208)
- Prague: (50.08804, 14.42076)
- München: (48.13743, 11.57549)
- Amsterdam: (52.37403, 4.88969) Mivel rögzítettek, így előre kikerestem a paramétereket ezen a weboldalon, ez a szolgáltatás is beépíthető később az alkalmazásba.

Ezeket a paramétereket (bár perzisztens adatok) egyelőre alkalmazás paraméterként fogom tárolni, nem érdemes erre adatbázist tenni az alkalmazás mellé.

gplesz commented 5 years ago

A visual studio code REST Client extension-jével tudom tesztelni és dokumentálni is az API hívást, így ezt fogom használni a felderítéshez.

gplesz commented 5 years ago

Az első hívás sikeres, egyelőre túl sok információt kapok vissza, nekem csak az aktuális és a hét napos előrejelzésre van szükségem naponta, így a fölösleget ki kell tiltanom. Ezek szerint valami ilyen lesz a kérésem:

https://api.darksky.net/forecast/[apikey]/47.49801,19.03991?exclude=minutely,hourly,alerts&lang=hu&units=auto

a lang paramétert a felületről fogjuk kapni, a units=auto a mértékegységeket a lekérdezett hely szerint állítja be, ez veszélyes lehet, így inkább fixáljuk si-re:

https://api.darksky.net/forecast/[apikey]/47.49801,19.03991?exclude=minutely,hourly,alerts&lang=hu&units=si

ez ilyen mértékegységeket használ:

SI units are as follows:

summary: Any summaries containing temperature or snow accumulation units will have their values in degrees Celsius or in centimeters (respectively). nearestStormDistance: Kilometers. precipIntensity: Millimeters per hour. precipIntensityMax: Millimeters per hour. precipAccumulation: Centimeters. temperature: Degrees Celsius. temperatureMin: Degrees Celsius. temperatureMax: Degrees Celsius. apparentTemperature: Degrees Celsius. dewPoint: Degrees Celsius. windSpeed: Meters per second. pressure: Hectopascals. visibility: Kilometers.

Ezt már be tudjuk fixálni a felületre, nem lesznek téves adatok megjelenítve még véletlenül sem.

gplesz commented 5 years ago

A visszatérő értékek közül az X-Forecast-API-Calls fejléc érdekes, ez jelzi, hogy a mai nap mennyi hívást indítottunk, így látszik, hogy mennyi inygenes lehetőség van még, illetve, ha fizetős szolgáltatásba csúsztunk akkor hol tartunk.

gplesz commented 5 years ago

A visszaadott adatok modelljéhez induljunk ki egyrészt azokból az adatokból, amiket a feladat kiírás vár tőlünk:

Temperature
Apparent (feels-like) temperature
Atmospheric pressure
Wind speed
Humidity
UV index

illetve a bejövő adatokból, amit mindenképpen érdemes parse-olnunk. Ez az aktuális adatokra így néz ki:

"currently": {
    "time": 1545123967,
    "summary": "Közepes felhősödés",
    "icon": "partly-cloudy-day",
    "precipIntensity": 0,
    "precipProbability": 0,
    "temperature": -9.36,
    "apparentTemperature": -9.36,
    "dewPoint": -11,
    "humidity": 0.88,
    "pressure": 1030.74,
    "windSpeed": 0.2,
    "windGust": 1.4,
    "windBearing": 353,
    "cloudCover": 0.58,
    "uvIndex": 0,
    "visibility": 5.02,
    "ozone": 333.8
  }

a napi előrejelzés pedig ilyenekből áll:

"data": [{
      "time": 1545087600,
      "summary": "Ködös idő reggel.",
      "icon": "fog",
      "sunriseTime": 1545114502,
      "sunsetTime": 1545144910,
      "moonPhase": 0.35,
      "precipIntensity": 0.0025,
      "precipIntensityMax": 0.0076,
      "precipIntensityMaxTime": 1545156000,
      "precipProbability": 0.01,
      "precipAccumulation": 0.053,
      "precipType": "snow",
      "temperatureHigh": -1.01,
      "temperatureHighTime": 1545134400,
      "temperatureLow": -4.87,
      "temperatureLowTime": 1545184800,
      "apparentTemperatureHigh": -1.01,
      "apparentTemperatureHighTime": 1545134400,
      "apparentTemperatureLow": -7.07,
      "apparentTemperatureLowTime": 1545202800,
      "dewPoint": -8.54,
      "humidity": 0.86,
      "pressure": 1030.03,
      "windSpeed": 0.43,
      "windGust": 2.62,
      "windGustTime": 1545087600,
      "windBearing": 322,
      "cloudCover": 0.69,
      "uvIndex": 1,
      "uvIndexTime": 1545127200,
      "visibility": 13.36,
      "ozone": 328.87,
      "temperatureMin": -12.68,
      "temperatureMinTime": 1545112800,
      "temperatureMax": -1.01,
      "temperatureMaxTime": 1545134400,
      "apparentTemperatureMin": -15.16,
      "apparentTemperatureMinTime": 1545094800,
      "apparentTemperatureMax": -1.01,
      "apparentTemperatureMaxTime": 1545134400
    }]

gplesz commented 5 years ago

Felhasználva a visual studio szolgáltatását, a visszatérő adatok json-jéből generáltatok

Amire figyelni kell: unix időszámítást használnak az adatok, ezeket majd időponttá kell alakítani. Ezt az Automapperre bízhatjuk.

gplesz commented 5 years ago

Küldéskor beállíthatjuk a

Accept-Encoding: gzip

fejlécet, hogy használjuk a http tömörítést.

gplesz commented 5 years ago

A következő lépés a darksky api és a teszjeinek a létrehozása, ott tudom folytatni a modell készítését.

gplesz commented 5 years ago

Az API wrapper-t dotnet standard környezetre írom, így wpf-ből is tudom hivatkozni, de (.net core) multiplatform is lehet. Ezen kívül kipróbálom a SpecFlow-t, .net core-ból még nem használtam, preview van csak, de egy próbát megér.

A wpf alkalmazás 4.7.1-es dotnet framework-öt fog használni, mivel nincs egyéb megkötés a feladatkiírásban.

gplesz commented 5 years ago

egyből létrehozom a wpf alkalmazást is, hogy a referenciák biztosan működjenek végig.

gplesz commented 5 years ago

hogy ne okozzon gondot a csomagok hivatkozása projekteken átívelő módon, beállítom, hogy a nuget ne packages.config.ot, hanem packagereferencet használjon:

https://www.hanselman.com/blog/ReferencingNETStandardAssembliesFromBothNETCoreAndNETFramework.aspx

gplesz commented 5 years ago

illetve, kialakítom a teszt környezetet is, .net core és specflow alapokon

gplesz commented 5 years ago

Fontos tervezési pont, hogy az API bemeneti adatokat hol állítjuk elő.

A város koordinátái a felöletről jönnek, mivel így a legegyszerűbb paraméterként tárolni/karbantartani, és az API ezt várja adatként, így nem érdemes az alkalmazás többi része elől ezt elrejteni.
a nyelv adatok a felületről jönnek
a mértékegység adatok a felületről jönnek (és rögzítettek, hogy a megjelenítés egyszerűbb legyen)
a megszorítás adatok az API rétegben rögzítve vannak.

gplesz commented 5 years ago

Mivel a RestSharp támogatja automatikusan a http tömorítést, ezért azt fogom használni a könyvtárhoz.

gplesz commented 5 years ago

Az apikulcs a http tesztállományban szerepel, a tesztforgatókönyvekben is fog, mert ennek elrejtésével most nem akarok időt veszteni, az alkalmazást is egyszerűbb ellenőrizni, ha minden rendelkezésre áll.

gplesz commented 5 years ago

Különösebben nagy hibakezelést nem építek be, az api egy boolean-t ad vissza, hogy sikeres volt-e a hívás vagy sem. Emellett naplót ír, később szofisztikálható, hogy mit csináljon a különböző hibáknál.

gplesz commented 5 years ago

Az API Wrapper prototípus szinten elkészült, a tesztekkel kapcsolatosan lehet majd bővíteni és javítsani, de a prototípushoz eleget tud.

gplesz / darksky

Specifikáció az API wrapperhez #2