API per le scuole di sci

Le chiavi sono della scuola, non di una persona, e solo il titolare della scuola può crearle o revocarle, dalla scheda Connessioni del pannello. Una chiave si mostra una sola volta, alla creazione; conserviamo un hash e non possiamo mostrarla di nuovo. Una scuola può avere fino a 5 chiavi attive, così ogni integrazione ha la sua e una vecchia si revoca senza toccare le altre. Le chiavi reali iniziano con ap_live_; quelle dell'ambiente di prova iniziano con ap_test_ e si contano a parte.

Una chiave smette di funzionare nel momento in cui viene revocata, e tutte ricevono un 403 school_not_active quando la scuola viene chiusa o non è approvata. Una scuola soltanto sospesa (nascosta dal sito, senza la sua pagina) conserva le chiavi: le sue prenotazioni vanno avanti, e l'API con loro. Le chiavi non si gestiscono dall'API stessa. Per ruotarne una: crea la nuova, passa il tuo sistema a quella e revoca la vecchia; nel frattempo valgono entrambe. Il pannello mostra quando ogni chiave è stata usata l'ultima volta, con 5 minuti di precisione. Le chiavi sono per i server: non metterne mai una in un browser o in un'app mobile.

Ogni richiesta porta la chiave come bearer token. L'URL di base è https://alpinepal.com/api/v1; le risposte sono JSON, mai in cache, e ognuna porta un X-Request-Id che puoi citarci. Le ore del giorno sono sull'orologio della stazione come HH:mm, le date come YYYY-MM-DD e gli istanti in ISO 8601 in UTC con millisecondi.

I corpi devono essere JSON con intestazione Content-Type: application/json (altrimenti 415), sotto i 256 KB (413), e vengono controllati in modo stretto: un campo sconosciuto è un 400 validation_error che elenca i percorsi di troppo. Un corpo vuoto si legge come oggetto vuoto. Un metodo che il percorso non ammette è un 405 con intestazione Allow; una barra finale è un 404.

Non c'è CORS: l'API è da server a server, e una richiesta da un browser fallirà. È voluto: una chiave in un browser è una chiave che chiunque può leggere.

Per chiave, in finestre fisse di un minuto: 600 letture (GET) e 120 scritture (tutto il resto, DELETE compreso) al minuto. Oltre, la risposta è 429 rate_limited con intestazione Retry-After, in secondi. Una chiave di prova ha una quota propria. I fallimenti di autenticazione si limitano per IP, 20 in 10 minuti; da lì in poi ogni altro tentativo riceve 429 prima ancora che la chiave venga cercata. Test e reinvii dei webhook condividono una quota a parte di 10 in 10 minuti per chiave, perché ognuno è una richiesta al server di qualcun altro.

Ogni errore è la stessa busta: uno stato HTTP, un code stabile su cui ramificare, un messaggio per una persona e l'id della richiesta. Cinque codici portano details: validation_error elenca i campi sbagliati come [{path, message}] (al massimo 10); booking_state dice in che stato è ora la prenotazione ({bookingStatus}); booking_conflict indica le ore che intralciano e, se quella prenotazione è pagata, il suo id e riferimento; rate_limited ripete l'attesa come {retryAfterSeconds}; inside_notice_window indica il preavviso del maestro in ore ({hours}).

Id. I maestri portano l'id del loro account (user_…), oppure unclaimed_… finché nessuno ha rivendicato un profilo che la tua scuola ha aggiunto senza account; il posto per lezioni non assegnate di una scuola è pool_<schoolId>; i maestri dell'ambiente di prova sono sandbox_ia_… e sandbox_ib_…. Le prenotazioni sono b_…, gli eventi evt_…, le consegne whd_…, gli endpoint wh_…, le richieste req_…. I riferimenti sono AP-<anno>-<5 cifre> per le prenotazioni reali e SB<6 hex> nell'ambiente di prova.

Orari. date, startTime ed endTime sono l'orologio a muro di resortTimeZone, mai UTC; gli istanti (createdAt, updatedAt, paidAt, instructorResponseDeadline…) sono UTC. Una lezione nella notte del cambio d'ora si risolve alla prima occorrenza di un'ora ambigua, e un'ora che quella notte non esiste va avanti. endTime può essere 24:00. Se un'ora è passata si giudica sull'orologio della stazione.

Denaro. subtotal = (hourlyPrice + extraStudentPrice × max(0, numberOfStudents − includedStudents)) × durationHours, arrotondato alla valuta; è ciò che paga il cliente. hourlyPrice è quello della data della lezione: quello di una stagione (seasonPrices) se la data vi rientra, altrimenti quello proprio del maestro o del posto; includedStudents è quanti allievi copre, 1 salvo che la scuola ne indichi di più. platformFee è la nostra commissione: il 10 %, o quella più alta che la tua scuola ha concordato per iscritto con noi; ogni prenotazione conserva quella con cui è stata venduta. netAmount è il resto, subtotal − platformFee, accreditato sul registro della tua scuola quando la lezione si completa, chiunque l'abbia tenuta e chiunque lo gestisca, e annullato se la prenotazione viene rimborsata. Ogni maestro nel tuo organico fattura nella valuta della tua scuola; i prezzi orari hanno un minimo per valuta (10 EUR, 11 USD, 10 CHF) ed extraStudentPrice è 0 o più. Anche l'attrezzatura che il cliente noleggia dalla tua scuola con la lezione si somma a subtotal (equipment.amount) e conta come la lezione.

managedBy è la regola che decide chi risponde: quando dice instructor, calendario e richieste sono suoi e l'API può leggere ma non scrivere; quando dice school, la scuola, e quindi l'API, scrive il calendario e risponde alle richieste, e il maestro guarda. Si imposta dall'organico nel pannello, da una persona, e non si cambia via API. Restituire il calendario al maestro cancella i blocchi esterni che il tuo sistema vi aveva scritto.

Quando un maestro lascia la scuola, le sue prenotazioni spariscono da GET /bookings e i suoi eventi si fermano, mentre ciò che ha già guadagnato resta sul tuo registro. Né questo né un cambio di managedBy manda un evento: confronta GET /instructors a ogni sincronizzazione.

unclaimed indica un maestro che la scuola ha aggiunto nel pannello senza account: nessuno accede con il suo nome, quindi è sempre managedBy school e la scuola risponde per lui in tutto, chat compresa. Quando la persona rivendica il profilo con il proprio account, unclaimed diventa false e l'id del maestro cambia in uno definitivo: tutti i percorsi e il filtro instructorId continuano ad accettare il vecchio id, il maestro lo riporta in previousId e gli eventi da quel momento citano quello nuovo. Nessun evento lo annuncia: confronta GET /instructors a ogni sincronizzazione e abbina previousId.

La disponibilità di un maestro è una lista di blocchi. Un blocco è available, blocked o vacation, appartiene a una stazione in cui il maestro insegna, va da startTime a endTime (endTime può essere 24:00), ed è ancorato o a un giorno della settimana (dayOfWeek 0–6, domenica per prima, opzionalmente con since e until come prima e ultima data in cui vale) o a una data precisa: esattamente uno dei due. Le nuove ore available devono stare tra le 07:00 e le 21:00, ora della stazione (altrimenti 422 outside_ski_day); i blocchi blocked e vacation possono coprire qualsiasi orario. I clienti possono prenotare solo dentro blocchi available che nient'altro copre.

PUT /instructors/{id}/availability sostituisce l'intero orario, ogni stazione e ogni blocco, fino a 400, con ciò che invii, esattamente come salvare il calendario nel pannello. Gli id sono facoltativi: il server ne assegna uno a un blocco che non ce l'ha, conserva quelli che invii e rifiuta duplicati o il prefisso xb_ dei blocchi esterni. I blocchi esterni (sotto) non vengono mai toccati dal PUT e non devono comparirvi. Un blocco malformato, una stazione sconosciuta, i due ancoraggi insieme o un since successivo all'until del blocco sono un 422 invalid_availability. I blocchi che non possono più valere (una data passata, un blocco settimanale oltre il suo until) vengono scartati: il PUT non li salva e il GET non li restituisce. Una data è passata quando lo è ovunque, alle 12:00 UTC del giorno dopo.

GET …/availability/expanded fa i conti per te: per una stazione e fino a 62 giorni restituisce, per giorno, le fasce libere che un cliente potrebbe prenotare e quelle occupate, ognuna etichettata booking (una lezione confermata), pending (una richiesta pagata in attesa di risposta) o external (un blocco dall'API). Applica il margine tra le lezioni e il preavviso fissato dal maestro; non scarta i buchi più corti della sua durata minima, quindi un buco di trenta minuti risulta libero.

Una lezione venduta fuori da Alpine Pal occupa il maestro. Registrala come blocco esterno e la fascia sparisce dalla ricerca, in ogni stazione in cui insegna: una persona non può stare in due valli insieme. I blocchi richiedono che la scuola gestisca il maestro (managedBy = school).

Ogni blocco porta il tuo externalRef. Inviare lo stesso riferimento con la stessa data e le stesse ore è idempotente e restituisce 200 con il blocco salvato, qualunque resortId tu passi; lo stesso riferimento con altre ore è un 409 external_ref_exists: cancella e ricrea. Un blocco che si sovrappone a una prenotazione viva è un 409 booking_conflict con le ore che intralciano e, se quella prenotazione è pagata, il suo id e riferimento: quella lezione è già venduta da noi.

Un maestro può avere al massimo 400 blocchi esterni da oggi in poi; uno in più è un 422 limit_reached. Un blocco la cui data è passata (alle 12:00 UTC del giorno dopo) se ne va da solo: GET /blocks non lo elenca più, un DELETE su di esso è un 404 e smette di contare per i 400.

Accettare una richiesta ricontrolla la fascia: un blocco esterno sulle sue ore, come una prenotazione viva o una lezione di gruppo, dà un 409 slot_conflict, e la scuola deve rifiutarla o proporre un altro orario. Sul posto senza maestro accettare non ricontrolla nulla: i suoi posti sono stati contati quando il cliente ha pagato. Quando il tuo blocco riceve 201 l'ora è tua: un pagamento già in corso su quell'ora viene rimborsato quando prova a concludersi e ti arriva come booking.expired.

Una scuola può vendere ore senza dire chi terrà la lezione: il cliente prenota e paga, e la scuola assegna un maestro quando vuole, via API, dal pannello o al punto d'incontro con chi è libero. Nell'API questo è il posto della scuola stessa: ha un calendario, un prezzo e un interruttore di conferma immediata propri, non compare in /instructors, e le sue prenotazioni arrivano con unassigned: true e instructorId uguale al posto (pool_…). Vende tante lezioni contemporaneamente quante ne consente la capacity del suo calendario: un blocco available può indicarla (fino a 50; 1 se manca), contata nella stazione del blocco minuto per minuto: i blocchi del giorno stesso sostituiscono quelli settimanali nei minuti che coprono, e all'interno di ciascuno i blocchi sovrapposti si sommano. Una lezione ha bisogno di un posto libero per tutta la sua durata. Le lezioni di gruppo del posto non occupano posti: si tengono insieme alle private e ad altre lezioni.

GET /unassigned mostra le impostazioni; PATCH /unassigned imposta uno qualsiasi tra hourlyPrice, extraStudentPrice (0 o più; uno negativo è un 422 invalid_price), extraStudentPer, durationPrices, seasonPrices, includedStudents, autoAcceptBookings e maximumStudents. Il primo PATCH crea il posto, e fino ad allora i suoi endpoint di calendario e blocchi danno 404. Non c'è un interruttore: active dice se il posto è in vendita, e lo è non appena il suo prezzo orario supera il minimo (o, se vende formati, formati e stagioni sono completi); vende nelle ore che apre il suo calendario, quindi una scuola che non vuole queste lezioni non ne apre nessuna. Un active in un PATCH viene ignorato. Per il resto, il calendario del posto funziona come quello di un maestro, nelle stazioni della scuola.

Formati fissi. Invece che a ore, una scuola può vendere le lezioni private del suo posto in formati fissi, impostati nel pannello: fino a 6 (mattino, pomeriggio, giornata intera o altro, ognuno con il suo inizio e la sua fine) e stagioni, periodi di date con un prezzo per formato, a lezione per tutto il gruppo. saleMode in GET /unassigned dice quale dei due, e lessonFormats elenca formati e stagioni (in sola lettura nell'API). Finché il posto vende formati, ogni sua lezione privata è uno di essi: un formato senza prezzo nella stagione di una data non si vende quel giorno, e una data fuori da ogni stagione non vende nulla. Un formato ha bisogno di un posto libero per tutto il suo orario, come ogni lezione del posto, e non ha il limite di 6 ore delle lezioni a ore. Un posto così è in vendita non appena formati e stagioni sono completi, qualunque sia il suo prezzo orario. Le sue prenotazioni portano format (id e tipo), subtotal è il prezzo di quel formato quel giorno, e propose-time lo sposta solo allo stesso orario in un giorno che venda il suo formato al prezzo pagato (altrimenti 409 format_fixed_time o format_price_differs). Nell'ambiente di prova, POST /sandbox/bookings sul posto accetta formatId e usa i formati della tua scuola.

Finché la lezione non è assegnata, la scuola è il suo lato maestro: risponde alla richiesta, chatta con il cliente e concorda il punto d'incontro. Una volta assegnata, la prenotazione è del maestro come qualsiasi altra, e ciò che la scuola può ancora farne segue managedBy.

Una lezione di gruppo è un evento con posti che clienti indipendenti comprano separatamente: singola (date) o serie settimanale (dayOfWeek, con since e until facoltativi), con una capienza, un prezzo a posto per l'intera lezione, un livello, per chi è (audience: tutti, bambini o adulti; una lezione per bambini può indicare minAge e maxAge, e ogni allievo che prenota un posto deve rientrarci), un punto d'incontro fisso e un minimo di partecipanti perché si tenga. Le lezioni di un maestro prendono il prezzo a posto dalle impostazioni del maestro stesso (groupClassesEnabled e groupPricePerStudent, scrivibili con PATCH /instructors/{id}); solo il posto senza maestro lo indica alla creazione, e un cambio di prezzo ritimbra le lezioni attive. Le lezioni si pubblicano, si affidano a un maestro e si annullano dal pannello — sull'API sono di sola lettura nella v1 — e vivono su un maestro dell'organico o sul posto senza maestro assegnato.

GET /instructors/{id}/classes (e GET /unassigned/classes) elencano quelle attive. GET …/classes/expanded?from&to le risolve in date concrete con i posti occupati, pagamenti in corso entro i loro 10 minuti di blocco inclusi — al massimo 62 giorni per chiamata. Sul calendario di un maestro le ore di una lezione risultano inoltre occupate nella vista espansa della disponibilità, e un blocco esterno su di esse viene rifiutato con un 409 booking_conflict: quelle ore non sono tue da vendere altrove. Il posto senza maestro assegnato è una squadra: le sue lezioni non tolgono posti alle private, si tengono insieme a loro e ad altre lezioni, e un blocco esterno non si scontra mai con esse.

Ogni posto venduto arriva da /bookings come una prenotazione normale con il suo groupClassId, confermata appena pagata (acceptedVia auto). propose-time e assign la rifiutano — l'orario è della lezione e di tutti i suoi partecipanti, e una lezione passa a un maestro intera, dal pannello. Annullare una lezione (o un giorno della serie) rimborsa ogni posto per intero e invia un booking.cancelled per posto; una lezione che 24 ore prima dell'inizio è ancora sotto il suo minStudents viene annullata allo stesso modo, con cancelledBy platform.

All'API arrivano solo prenotazioni pagate: una prenotazione esiste per te dall'istante in cui entra il pagamento (paidAt), e una rimborsata resta elencata con il suo paymentStatus. Un cliente sceglie maestro e fascia, paga, e la richiesta arriva al maestro o alla scuola. Da lì, o riceve risposta, o scade senza risposta e il cliente viene rimborsato.

L'orologio: il termine di risposta è 48 ore dal pagamento, mai oltre l'inizio della lezione; una proposta o un suo rifiuto lo azzerano (mai oltre il primo tra l'inizio originale e quello proposto); una scansione oraria fa scadere ciò che è in ritardo, quindi la scadenza può arrivare fino a un'ora dopo. Una lezione confermata diventa upcoming 24 ore prima dell'inizio e in_progress mentre si svolge. Si completa quando il cliente la conferma, o da sola 48 ore dopo la fine; il completamento libera la tua parte. Il cliente può annullare gratis fino a freeCancellationHours ore prima dell'inizio: il termine della prenotazione stessa, quello che aveva la politica di cancellazione della tua scuola quando è stata fatta (48 di default), e che mantiene anche se la politica cambia dopo.

Del cliente ricevi un nome breve (nome e iniziale), la lingua preferita e il messaggio: quanto basta per tenere la lezione, e ciò che la nostra informativa sulla privacy gli promette. Email, telefono e qualsiasi identificativo dell'account non vengono mai inviati; la conversazione con il cliente resta nella chat di Alpine Pal, dov'è il maestro.

GET /bookings elenca le prenotazioni pagate dei tuoi maestri, dalla modifica più vecchia alla più nuova, con filtri per status (lista separata da virgole), instructorId, from e to (date della lezione) e updatedSince (qualsiasi istante ISO 8601; inclusivo). Le pagine vanno per cursore su (updatedAt, id): segui nextCursor finché è null. Il cursore è opaco e non scade, ma appartiene ai filtri con cui è stato creato: se li cambi, ricomincia; uno inventato è un 400.

Lo schema per una sincronizzazione notturna o oraria è lo stesso: ricorda l'updatedAt più recente che hai visto e chiedi tutto da lì, così come l'hai ricevuto. I webhook ti avvisano nel momento in cui qualcosa cambia; questo endpoint è come ti rimetti in pari dopo un'interruzione. updatedAt si muove anche per cambi che non mandano eventi (la lezione che diventa upcoming o in_progress, un promemoria inviato), quindi una riga può comparire in una sincronizzazione senza nulla di visibilmente diverso.

Le azioni sono aperte alla scuola sui maestri che gestisce e sul proprio posto per lezioni non assegnate; su un maestro che si gestisce da sé la risposta è 403 not_managed_by_school. Ogni azione è un aggiornamento condizionale: se la prenotazione non è più nello stato che l'azione si aspetta, la risposta è 409 booking_state con lo stato attuale in details, e non cambia nulla. Ripetere un'azione è quindi sicuro, e il modo per confermare cosa è successo è GET /bookings/{id}.

Due cose non ci sono di proposito: segnare un'assenza e dare una lezione per completata. Entrambe muovono denaro in base a ciò che è successo in pista, ed entrambe restano un atto umano nel pannello.

Registra un URL https e facciamo POST di ogni evento di prenotazione lì: lo stesso JSON che restituiscono gli endpoint delle prenotazioni, avvolto in un evento. Fino a 10 endpoint per scuola, ognuno iscritto ad alcuni eventi o a tutti con "*". Registrali dal pannello o via API; il pannello mostra il registro delle consegne in entrambi i casi. L'URL deve essere https, con un nome host che abbia un punto, senza credenziali né frammento, e non un indirizzo privato né il nostro.

Eventi. booking.requested: è arrivata una richiesta pagata. booking.confirmed: accettata dal maestro o dalla scuola, confermata automaticamente, o il cliente ha accettato un orario proposto; acceptedVia dice quale, e previousStatus è change_proposed nell'ultimo caso. booking.time_proposed: al cliente è stato proposto un altro orario. booking.rejected. booking.cancelled: cancelledBy è customer, instructor, school o platform (l'account dietro la prenotazione è stato eliminato, o una lezione di gruppo è stata annullata per non aver raggiunto il suo minimo). booking.expired: nessuno ha risposto in tempo. booking.completed: la lezione è finita, assenze comprese. booking.updated: qualsiasi altra cosa che meriti un avviso, con data.reason: proposal_declined, meeting_point_proposed, meeting_point_confirmed, dispute_opened, dispute_resolved, refund_settled (il denaro è tornato al cliente), refund_issued (da noi) o instructor_assigned (previousInstructorId indica il posto su cui stava la lezione). ping è l'evento di prova, con data vuoto; non è un tipo a cui iscriversi. Nessun evento per upcoming, in_progress, né per cambi di organico o di managedBy.

Cosa aspettarsi. La consegna è almeno una volta: una risposta che arriva dopo i nostri 10 secondi di attesa conta come fallimento e l'evento torna, quindi tratta l'id dell'evento come chiave e ignora le ripetizioni. L'ordine non è garantito, i nuovi tentativi e la scansione lo alterano, quindi ordina per data.booking.updatedAt. Non ogni prenotazione comincia con booking.requested: quella di un maestro con la conferma immediata attiva (autoAcceptBookings) arriva direttamente come booking.confirmed, con previousStatus pending_instructor_approval. Quindi registra la prenotazione nel tuo sistema al primo evento che vedi per il suo id, di qualunque tipo sia. Il payload è congelato alla creazione dell'evento; un nuovo tentativo porta ciò che era vero allora, e un evento successivo lo stato più nuovo. Un evento può andare perso se fallisce il nostro tentativo di registrarlo; GET /bookings?updatedSince è la rete di sicurezza. Ogni evento porta sandbox: true o false. Il registro conserva le consegne 30 giorni; un reinvio manda di nuovo una consegna passata.

Ogni consegna è firmata con il segreto dell'endpoint: l'intestazione X-AlpinePal-Signature porta una marca temporale e un HMAC-SHA256 della marca, un punto e il corpo grezzo. Verificala prima di fidarti di qualsiasi cosa, confronta in tempo costante e rifiuta marche a più di 5 minuti dal tuo orologio. Il segreto viene restituito alla creazione dell'endpoint e da GET /webhooks, e si può ruotare dal pannello o con POST /webhooks/{id}/rotate-secret; il vecchio muore all'istante.

Rispondi con un qualsiasi 2xx entro 10 secondi. Qualsiasi altra cosa, un 3xx compreso perché non seguiamo i reindirizzamenti, è un fallimento: riproviamo dopo 5 minuti, 15 minuti, 1 ora, 4 ore, 12 ore e 24 ore, circa 42 ore in tutto, ogni volta con lo stesso id di evento così puoi deduplicare. Un endpoint viene spento, e gli amministratori della scuola avvisati, solo quando una consegna ha esaurito tutti i tentativi senza che nel frattempo ne arrivi nessun'altra; una breve interruzione non lo spegne, anche con molti eventi in corso. Mentre è spento non gli si accodano eventi nuovi (GET /bookings?updatedSince ti rimette in pari), e una consegna in sospeso il cui tentativo scade in quel tempo passa a fallita senza essere inviata; i tentativi che scadono dopo che l'hai riacceso partono normalmente. Reinvia quelle fallite. POST /webhooks/{id}/test accoda un ping come una consegna qualsiasi, lo tenta subito e riferisce com'è andato quel tentativo: un ping fallito viene ritentato allo stesso modo, conta come qualsiasi consegna per lo spegnimento dell'endpoint e, con l'endpoint spento, passa a fallito senza essere inviato. GET /webhooks/{id}/deliveries mostra le consegne più recenti per prime, 50 di default e fino a 100 con ?limit=, con il conteggio dei tentativi e senza i corpi: ogni evento ha una consegna per endpoint, più una per ogni reinvio, con lo stesso id di evento.

Ogni scuola ha una gemella di prova dal momento in cui il titolare crea una chiave di prova nel pannello (Connessioni → Ambiente di prova): una copia della scuola con due maestri fittizi, sandbox_ia_…, che risponde alle richieste a mano, e sandbox_ib_…, con la conferma immediata attiva, e il posto per lezioni non assegnate, ciascuno con un calendario 09:00–17:00 tutti i giorni nelle stazioni della scuola, da 1 a 6 ore per lezione, fino a 6 allievi, senza margine né preavviso. Le chiavi di prova iniziano con ap_test_ e raggiungono solo la gemella; le chiavi reali mai. Tutto il resto è la stessa API: elencare i maestri della gemella, scrivere i loro calendari, registrare webhook, rispondere alle richieste, assegnare lezioni.

Quello che un cliente fa sul sito lo fa per te POST /sandbox/bookings: crea una prenotazione pagata per il maestro che indichi, con gli stessi controlli di una vera, disponibilità pubblicata e nessuna sovrapposizione, e senza soldi di mezzo. Da lì gira la macchina vera, e le azioni qui sotto fanno le veci del cliente e dell'orologio, così ogni evento si vede in pochi minuti. Nessuna email esce dall'ambiente di prova e niente di esso è mai pubblico; ogni evento che invia porta sandbox: true, come GET /me. POST /sandbox/reset lo svuota perché una batteria di test parta pulita.

Resta fuori dalla portata dell'ambiente di prova: reclami, assenze, un rimborso emesso da noi, un annullamento con cancelledBy platform e il punto d'incontro (i suoi eventi nascono sul sito). Le prenotazioni dell'ambiente di prova portano studentLevels vuoto e un cliente chiamato Sandbox C. che usa il sito in inglese.

La descrizione leggibile da una macchina vive su https://alpinepal.com/api/v1/openapi.json: ogni percorso, metodo, parametro e schema qui sopra, in OpenAPI 3.1. Puntaci un generatore per avere un client tipizzato, o importala nel tuo strumento HTTP per sfogliarla. Si serve senza autenticazione e resta in cache per un'ora.

Questa è la v1. Al suo interno aggiungiamo soltanto: campi nuovi, parametri facoltativi nuovi, tipi di evento nuovi, endpoint nuovi. La tua integrazione deve ignorare i campi e gli eventi che non conosce. Qualsiasi cosa che romperebbe un client esistente andrebbe in una v2 con un altro URL di base, con la v1 in funzione mentre migri.