Remote API

Syftet med detta dokument är att förklara:

1. ...hur Prenlys ekosystem gör det möjligt att hantera autentisering och auktorisering av användare med hjälp av en teknisk infrastruktur som ägs av utgivaren eller en tredje part.

2. ...hur en teknisk implementering kan göras genom att bygga ett modest rest-API som följer specifikationen "Prenly Remote authority API".

Kontakt

Vänligen kontakta oss via e-post på hello@prenly.com eller via telefon på +46-31-3884740 för frågor eller problem angående detta API.

Definitioner

Autentisering är processen att verifiera någons eller någots identitet, dvs. om de är den de utger sig för att vara, innan åtkomst till skyddade data beviljas. Normalt görs detta genom att tillhandahålla vissa referenser, t.ex. ett användarnamn och ett lösenord. Givet att uppgifterna matchar en lagrad post "verifieras" (autentiseras) användaren genom att tillämpa principen att användaren visste något som bara den "riktiga" användaren skulle veta.

Auktorisering är den process där man bestämmer vilka resurser en användare har tillgång till, dvs. vilka data användaren har behörighet att komma åt och vad användaren får eller inte får göra. För Prenly innebär detta att bestämma vilka publikationer som användaren kan se och öppna för att läsa.

Ett API(Application Program Interface)är en uppsättning rutiner, protokoll och verktyg för att hantera interaktionen mellan olika system eller delar av system, och dikterar kommunikationen mellan systemen.

I Prenly är en auktoritet en teknisk implementering som bestämmer hur autentisering och auktorisering hanteras av en Prenly-applikation i Prenlys backend.

Introduktion till

Prenly Remote Authority API ger möjlighet att ersätta Prenlys hantering av auktorisering och/eller autentisering genom att implementera API-slutpunkter som följer en API-specifikation, vilket gör det möjligt för en Prenly-kund att autentisera och auktorisera utifrån sitt system, sina krav och behov.

I grund och botten gör detta det möjligt för Prenly-applikationens myndighet att auktorisera och/eller autentisera användare när de interagerar med Prenly-applikationen, dvs. när de läser publikationer i en app, genom proxy av Prenly Remote Authority API.

Prenly-myndigheten kommer att förmedla autentiserings- och auktoriseringsförfrågningar mellan användare och Prenly där ingen direkt kommunikation tillåts mellan användare och API-implementering. Istället informerar API-implementeringen Prenly-myndigheten om hur den ska agera på användarnas autentiserings- och auktoriseringsförfrågningar.

Implementera ditt API

Förstå hur användaren använder Prenly-applikationen

Prenly-applikationer

Prenly förser slutanvändaren med applikationer som främst används för att läsa publikationer och artiklar. Applikationen är antingen en inbyggd mobilapp på Android- eller iOS-plattformen eller vår responsiva webbaserade e-läsare. Dessa två applikationstyper erbjuder en liknande användarupplevelse.

Applikationen kan innehålla publicerade publikationer som är offentliga för alla, samt skyddat innehåll som kräver någon form av tillstånd för att kunna konsumeras. För inbyggda appar är det också möjligt att låta alla icke-inloggade användare konsumera vissa publikationer gratis innan inloggning krävs.

Navigera i applikationen

När en användare använder applikationen kan han eller hon normalt se startsidan som innehåller komponenter som visar publicerade publikationer. Publika publikationer kan öppnas och läsas genom att välja publikationen. Men när användaren försöker öppna en skyddad publikation kommer programmet att kräva att användaren loggar in(autentisering).

Efter inloggningen avgör Prenly om den begärda publikationen är läsbar för den användaren(auktorisering). Om så är fallet öppnas publikationen och är redo att användas. Om användaren inte har läsåtkomst meddelas användaren i appen. Det skyddade innehållet kommer inte att visas, men användaren kommer fortfarande att vara inloggad.

I vissa fall kommer en applikation att kräva att användaren loggar in för att visa vissa publikationer, särskilt när inte alla publicerade publikationer kan ses av vem som helst. Till exempel publikationer som är tillgängliga via en prenumeration där andra publicerade publikationer som inte är prenumererade ska vara dolda.

Konfigurera en API-miljö

Förtroende för Prenly-förfrågningar

Prenly skickar en fördefinierad hemlig nyckel i alla autentiserings- och auktoriseringsförfrågningar. Nyckeln är endast känd av Prenly och ditt system. Du bör kontrollera att den tillhandahållna nyckeln matchar den förväntade nyckeln för alla API-förfrågningar.

Du kan också öppna upp dina API-slutpunkter för endast vissa IP-adresser för extra säkerhet. Kontakta oss för att få en uppdaterad lista över IP-adresser som Prenly kommer att använda i förfrågningar om du vill ha denna extra säkerhet.

Kryptera trafiken

Vi rekommenderar starkt att du inte tillåter någon okrypterad HTTP-trafik till ditt API. Använd HTTPS!

Tillåt ett REST-liknande beteende

Prenly-förfrågningar görs för närvarande med HTTP POST, men API:et bör inte vara begränsat till att använda några HTTP-metoder för framtida endpoint-expansion. Se den aktuella API-specifikationen för mer information eftersom API-specifikationen har sista ordet i eventuella avvikelser från denna dokumentation.

I API-svar används HTTP-statuskoder för att informera Prenly om resultatet. Du måste kunna svara med olika HTTP-statuskoder, både för lyckade förfrågningar och för datafel, körtidsfel och oväntade serverfel.

Parametrar för begäran skickas för närvarande som JSON i begärans kropp.

Alla slutpunkter svarar för närvarande med JSON i svarskroppen.

Bekanta dig med OpenAPI 3.0

API-specifikationen dokumenteras i en yaml-fil enligt OpenAPI 3.0-standarden (tidigare Swagger) och anger de tekniska aspekterna och kraven för API:et och varje slutpunkt, inklusive alla dataobjekt för begäran och svar.

Autogenererad dokumentation finns på https://apidoc.prenly.com/remote-api/ och specifikationsfilen finns på https://apidoc.prenly.com/remote-api/spec/v1.3-specification.yaml.

Gör gärna en kopia av specifikationsfilen och modifiera den till dina API-slutpunkter (URL:er) eftersom den autogenererade specifikationen innehåller generiska namngivna slutpunkter som referens. Med den här filen kan du enkelt bygga en testmiljö med färdiga verktyg som finns på https://openapi.tools/ (se avsnittet "Testing").

Läs mer om OpenAPI, inklusive specifikationen, på https://www.openapis.org/.

Bygga slutpunkten för autentisering

Se API-specifikationen på https://apidoc.prenly.com/remote-api/ för slutpunkterna för autentisering. Du kan välja slutpunktens URL precis som du vill, men slutpunkten måste följa API-specifikationen.

Parametrar för begäran

Begärandeparametrar är en del av begäran som JSON och skickas av Prenly för varje begäran.

Svar vid framgång

En lyckad inloggning måste svara med HTTP-statuskod 200 och ett JSON-svar med den unika identifieraren för den användare som autentiserades.

Svar vid misslyckande

Kända fel som beror på de angivna parametrarna för begäran måste svara med någon av HTTP-statuskoderna 401, 403 eller 412 enligt specifikationen i API-dokumentationen. Dessa fel måste innehålla ett JSON-svar som följer Error-datamodellen som du hittar längst ner på https://apidoc.prenly.com/remote-api/.

Du kan välja att antingen tillhandahålla ett Error eller ett tomt JSON-objekt. För närvarande krävs endast egenskapen "message" om du tillhandahåller ett Error. Det är dock rekommenderat att även ange en "code"-egenskap.

Vi rekommenderar starkt att du anger ett värde för egenskapen "message" på engelska som representerar felet på något sätt. Om din programvara har någon form av interna koder är det lämpligt att använda dem här om framtida ömsesidig felsökning kommer att behövas. Inkludera inte personuppgifter som inte behövs, t.ex. personnamn! Unika ID:n är tillräckligt bra för felsökning.

Denna information visas aldrig för slutanvändaren men kan loggas i Prenly för att förenkla felsökning.

Bygga slutpunkten för auktorisering

Se API-specifikationen på https://apidoc.prenly.com/remote-api/ för slutpunkterna för auktorisering. Du kan välja slutpunktens URL precis som du vill, men slutpunkten måste följa API-specifikationen.

Parametrar för begäran

Begärandeparametrar är en del av begäran som JSON och skickas av Prenly för varje begäran.

Svar vid framgång

En lyckad hämtning av användarinformationen måste svara med HTTP-statuskod 200 och ett JSON-svar enligt UserSummary-datamodellen som beskrivs i specifikationen.

Fälten i detta dataobjekt förklaras längst ned på https://apidoc.prenly.com/remote-api/.

Vad egenskaper används till

Den enda egenskapen som för närvarande inte kan lämnas tom är "uid". De andra egenskaperna kan utelämnas, men vi rekommenderar att du anger en "productCodes"-egenskap för att bättre kunna kontrollera om Prenly ska bevilja läsbehörighet till publikationer eller inte. För närvarande kommer Prenly att behandla en saknad "productCodes"-egenskap som en tom lista.

Svar vid misslyckande

Kända fel som beror på de angivna parametrarna för begäran måste svara med någon av HTTP-statuskoderna 403, 404 eller 412 enligt specifikationen i API-dokumentationen. Dessa fel måste innehålla ett JSON-svar som följer datamodellen Error enligt beskrivningen ovan.

Testning

Det är viktigt att testa din implementation för slutpunkterna för autentisering och auktorisering. Se https://docs.google .com/document/d/1UxmvDs7_Z0GwGbwCHXr4Ojpb9HaZif1nJ8YRMmztzeo/ för mer information om hur du testar dina endpoints.

Vad händer i Prenly?

När användaren loggar in (autentisering + auktorisering)

När användaren begär att få logga in och skickar in inloggningsformuläret skickas inloggningsuppgifterna till Prenlys myndighet (krypterade med SSL). Därifrån hanterar myndigheten hur man använder dessa referenser för att autentisera användaren. För API:et Remote authority innebär detta att autentiseringsuppgifterna skickas till fjärranslutningspunkten enligt specifikationen.

Prenly kommer att bearbeta API-svaret och hantera både lyckade och misslyckade autentiseringsförfrågningar där användaren kommer att se ett fel beroende på HTTP-statuskoden för felsvaret. Se nedan för mer information.

Om autentiseringen lyckades...

En lyckad inloggning kommer att trigga en separat auktoriseringsbegäran till API-slutpunkten för auktorisering för att hämta användarens information, som cachas i Prenly under en begränsad tid.

Applikationen kommer också att visa att någon är inloggad, med namn eller e-post baserat på vilka användardata som returnerades i användarinformationen.

Observera. Om en auktoriseringsbegäran direkt efter en inloggning returnerar en HTTP 401-respons kommer Prenly att tolka det som ett implementeringsfel, logga ut användaren och informera användaren om att hens inloggningsuppgifter var felaktiga. För att förhindra detta rekommenderas att använda tokenkonceptet som kan ses under UserIdentification-schemat om du är intresserad av att stödja fjärrutloggning av användaren.

Om inloggningsuppgifterna var felaktiga...

Om begäran var tekniskt framgångsrik, men autentiseringsuppgifterna var felaktiga, kommer Prenly-myndigheten att meddela applikationen och ett meddelande om felaktiga autentiseringsuppgifter kommer att presenteras för användaren.

Om något misslyckades...

Andra klient- eller serverbaserade fel, eller nätverksfel, fångas upp och loggas av Prenly. Programmet kommer att få ett lämpligt felmeddelande som presenteras för användaren.

När användaren fortsätter att läsa

Cachelagring för upprepade förfrågningar

Cachelagring av svarsdata från en lyckad auktorisering (användarens information) eliminerar behovet av upprepade förfrågningar till fjärr-API:t för att hämta användardata som sällan ändras. Varje Prenly-kund kan välja utgångstid för cacheminnet, vi rekommenderar att du ställer in 30 minuter, där den minsta tillåtna utgångstiden för cacheminnet är 20 minuter.

Återauktorisering

Prenly kommer att använda det cachade resultatet för varje auktoriseringsbegäran så länge som cacheminnet inte har löpt ut. Om cachen har löpt ut kommer Prenly att utlösa en ny auktoriseringsbegäran till auktoriseringsslutpunkten i fjärr-API:t. Detta kommer att uppdatera användarens data, t.ex. produkttillgänglighet, samt de cachade data.

Hantering av fel

Om ett serverfel (5xx HTTP-kod) inträffar när omauktorisering utlöses förlängs utgångstiden för cachen med fem minuter. Prenly gör detta för att undvika att användare loggas ut på grund av tillfälliga nätverks- eller serverfel; användaren fortsätter att läsa som om inget hänt, och efter fem minuter görs ett nytt omauktoriseringsförsök. Detta beteende varar så länge som serverproblemet kvarstår. Prenly kommer att logga sådana tekniska problem och försöka nå kunden om detta inträffar.

Att gå live

När du tror att API:et är redo att tas i drift (du är klar med att utveckla och testa din implementering), kontakta oss för att ta de sista stegen.

Prenly kommer att kräva information från dig för att konfigurera din implementering i Prenly. Informationen kommer att utvärderas och om allt är i sin ordning kan din implementering användas i Prenly för dina valda Prenly-applikationer för e-papper.

Konfigurera Prenly

Innan din implementering av fjärr-API:t kan användas i Prenly måste du tillhandahålla:

- Din valda hemliga nyckel för slutpunkterna för autentisering och auktorisering

- Dina valda API-slutpunkter

- En lista över produkter som ska ge läsbehörighet och för vilka Prenly-titeln (endast Prenly-kända produkter i produktkodlistan från auktoriseringsändpunkten kan ge läsbehörighet)

- Din önskade utgångstid för cachen

- En URL där en ny användare kan skapa ett konto

- En URL där en användare kan ta bort sitt konto

- En URL där en användare kan återställa sitt lösenord (om de har glömt sitt lösenord)

- Vi rekommenderar att du också tillhandahåller en URL där en auktoriserad användare utan några tidigare kända produktkoder kan aktivera en produkt (t.ex. köpa en prenumeration)

- Användaruppgifter (användarnamn och lösenord) för testanvändaren, där användaren delas av Textalk, Apple och Google (om du har inbyggda appar) där minst en produktkod måste förbli aktiv så länge som fjärr-API:t används av Prenly-myndigheten för ditt e-papper