# Utvecklarguide
Denna dokumentation vänder sig till dig som utvecklare som ska anpassa din applikation för att kunna använda detta API.

## API Specifikation
För att utforma REST API specifikationer använder myndigheten standarden [OpenAPI version 3](https://github.com/OAI/OpenAPI-Specification).
API specifikationen kan användas för att generera kod till din applikation. Tips på verktyg för kodgenerering finns [här](https://openapi.tools). 

### Förändringar 
Ett API ska vara stabilt och alla ändringar som görs ska vara båkåtkompatibla. Om detta inte kan uppfyllas kommer en ny version av detta API att publiceras. Den tidigare versionen kommer sedan under kontrollerade former att avvecklas.

#### Förbered applikationen på att kunna hantera bakåtkompatibla utökningar
Applikationer som änvänder ett API ska vara robusta och vara förberedda för att kunna hantera bakåtkompatibla ändringar av ett API. Det innebär att:

- Vara konservativa i anrop av ett API. Exempelvis ska inte data sättas utan att ha kontroll på dess längd.
- Vara toleranta med okända egenskaper i meddelandet som kan behövas i ett efterföljande PUT anrop.
- Vara förberedd på att x-extensible-enum kan leverera nya värden.
- Vara förberedd att HTTP statuskoder kan returneras som inte finns angivna i API specifikationen. Standardhantering av koder ska bygga på exempelvis 1XX, 2XX, 3XX och 4XX enligt [RFC7231 sektion 6](https://www.rfc-editor.org/rfc/rfc7231#section-6).
- Följ omdirigeringen när HTTP statuskod 301 returneras.

#### Utfasning
När ett API fasas ut kommer detta att synliggöras i API specifikationen samt att HTTP rubriker kommer att finnas med i svaret.

Exempel på utfasningsinformation i en API specifikationen
```
/resurs:
  get:
    deprecated: true
    description: This operation is deprecated and will be retired 2023-01-01. Instead use the operation getResourceById.
```

Exempel på utfasningsinformation i HTTP svaret
```
X-API-Deprecated: true
X-API-Retire-Time: 2023-01-01T12:00:00
```

## Tekniska begränsningar
API:et är konfigurerat för att tillåta maximalt 1000 anrop per minut. När denna nivå har uppnåts så returneras HTTP statuskod 429 "Too many requests".

## Säkerhet
Detta API är är en REST tjänst baserad på http och json. Kommunikation mot tjänsten krypteras via https.

## Miljöer
### Test
| Funktion | URL |
|----------|-----|
|gateway|https://gw-test.havochvatten.se|
|API|https://gw-test.havochvatten.se/external-public/fishing-regulations/v1|
|övervaka API:et|https://gw-test.havochvatten.se/external-public/fishing-regulations/v1/operations/health-checks/readiness|

### Produktion
| Funktion | URL |
|----------|-----|
|gateway|https://gw.havochvatten.se|
|API|https://gw.havochvatten.se/external-public/fishing-regulations/v1|
|övervaka API:et|https://gw.havochvatten.se/external-public/fishing-regulations/v1/operations/health-checks/readiness|

## Test
Du ansluter och testar i testmiljön. I testmiljön kan du säkerställa att du kan koppla upp din applikation mot API:et och att din applikation fungerar som det är tänkt. När testerna är avklarade och verifierade får du tillgång till produktionsmiljön.

### Testdata
#### sökväg /geographies
Ett mockat svar genereras vilket innebär att följande svar alltid returneras.
Se i [exempelfilen](../exempel/exempel) för exempel på svar.

## Övervakning
#### sökväg /operations/health-checks/readiness

För att säkerställa att api:et är tillgängligt finns det en resurs att anropa. Förväntat värde är "up" eller "down".
Exempel på svar.
```
{
  "readiness": {
    "description": "Service is ready",
    "state": "up"
  }
}
```

## Kontakt och support
Om du har ytterligare frågor eller behöver hjälp är du välkommen att kontakta oss. Du når oss via mejl på itsupport@havochvatten.se.

***
***
[Havs- och vattenmyndigheten](https://www.havochvatten.se)
