Felhantering
Om ytterligare information behöver delges konsumenten skall schemat som specificeras i RFC 7807 användas
Om HTTP svarskoderna inte räcker SKALL (FEL.01) API:et beskriva feldetaljer enligt schemat nedan.
Att beskriva feldetaljer (eng: problem details) är baserat på RFC 7807.
Schema för att beskriva feldetaljer
Schemat enligt RFC 7807 kan innehålla nedan attribut och kräver att mediatypen application/problem+json eller application/problem+xml används i svaret.
Attribut | Beskrivning |
---|---|
type | En URI som identifierar problemtypen som skall vara mer specialiserad än statuskoden. URI:n skall peka på dokumentation av feltypen om den används. |
title | En kort beskrivning av problemtypen. Dvs att beskrivningen alltid ska vara identisk för samma typ av fel. Om inte type är angivet skall title reflektera beskrivningen av statuskoden. |
status | Detsamma som statuskoden för HTTP-svaret om det används. Kan vara lämpligt att använda om svaret behöver vara självförklarande. |
detail | Kort beskrivning av det faktiska felet, avsedd för läsning av människa. |
instance | En URI som identifierar den faktiska resursen. |
Feldetaljer kan utökas med nya attribut.
Exempel:
curl -X POST "https://gw.api.bolagsverket.se/foretagsinformation/v2/organisationer/1234567-922/kontaktuppgifter" \
-H "Accept: */*" -H "Content-Type: application/json" \
-d '{"email":"lisa.testperson@example.se"}' -i
HTTP/1.1 400
Content-Type: application/problem+json
{
"type" : "https://example.com/probs/req-parameters",
"title" : "Felaktiga anropsparametrar",
"status" : 400,
"detail" : "Felaktigt organisationsnummer",
"instance" : "/foretagsinformation/v2/organisationer/1234567-922",
"invalid-parameters" : [
{
"reason" : "Organisationsnummer ej giltigt",
"value" : "1234567-922",
"property" : "organisationsnummer"
}
]
}
Utökning med nya attribut
I exemplet ovan är invalid-parameters en utökning. Konsumenter av ett API skall ignorera utökningar som de inte känner igen.
Notera!
Det är inte möjligt att utöka med nya ”standardattribut” utan att ändra mediatypen med denna design.
Utökning med identifierare för ett specifikt fel
För att underlätta felsökning och få en ökad spårbarhet kan en identifierare för det specifika felet förmedlas till konsumenten. Om det mönstret tillämpas skall identifieraren förmedlas på följande sätt.
HTTP/1.1 400
Content-Type: application/problem+json
{
"type" : "https://example.com/probs/req-parameters",
"title" : "Felaktiga anropsparametrar",
"status" : 400,
"detail" : "Felaktigt organisationsnummer",
"instance" : "/foretagsinformation/v2/organisationer/1234567-922",
"invalid-parameters" : [
{
"reason" : "Organisationsnummer ej giltigt",
"value" : "1234567-922",
"property" : "organisationsnummer",
}
]
"transaction-id": "86032cbe-a804-4c3b-86ce-ec3041e3effc"
}