Ett API för romerska siffror

I dag är det .

Jag har precis lagt till ett litet API på roman.tammergard.se för att konvertera mellan arabiska och romerska siffror.

Alla endpoints ligger under /api/v1/, returnerar JSON och har CORS aktiverat för alla domäner. Statiska endpoints (/to, /from, /validate, /convert, /all) CDN-cachas i en vecka, medan /today cachas fram till nästa midnatt i Europe/Stockholm så att gårdagens datum inte ligger kvar efter midnatt. Det tillåtna intervallet är 1–3999, vilket är intervallet klassiska romerska siffror täcker. Fullständig dokumentation på roman.tammergard.se/api.

I dag

const res = await fetch("https://roman.tammergard.se/api/v1/today")
const data = await res.json()

Live-svar just nu:

Arabiska till romerska

await fetch("https://roman.tammergard.se/api/v1/to/2026")
// {
//   arabic: 2026,
//   roman: "MMXXVI"
// }

Romerska till arabiska

await fetch("https://roman.tammergard.se/api/v1/from/MMXXVI")
// {
//   roman: "MMXXVI",
//   arabic: 2026
// }

Konvertera åt båda hållen

await fetch("https://roman.tammergard.se/api/v1/convert/MMXXVI")
// {
//   kind: "roman",
//   input: "MMXXVI",
//   roman: "MMXXVI",
//   arabic: 2026
// }

Fältet kind visar från vilket håll indata tolkades. Skicka in en arabisk siffra för att vända det:

await fetch("https://roman.tammergard.se/api/v1/convert/2026")
// {
//   kind: "arabic",
//   input: "2026",
//   arabic: 2026,
//   roman: "MMXXVI"
// }

Validera

await fetch("https://roman.tammergard.se/api/v1/validate/MMXXVI")
// {
//   input: "MMXXVI",
//   normalized: "MMXXVI",
//   valid: true
// }

Indatan normaliseras (trimmas och versaliseras) före valideringen, så mmxxvi är lika giltig som MMXXVI.

Alla siffror

await fetch("https://roman.tammergard.se/api/v1/all")
// [
//   { arabic: 1, roman: "I" },
//   { arabic: 2, roman: "II" },
//   ...
//   { arabic: 3999, roman: "MMMCMXCIX" }
// ]

Svaret är runt 100 KB. Praktiskt om man hellre vill skicka hela tabellen till klienten och slå upp lokalt.

Fel

Felsvaren följer RFC 9110 och skiljer på felformaterad indata och semantiskt ogiltig indata. Felformaterade värden – till exempel en sträng där ett heltal förväntas – returnerar 400:

await fetch("https://roman.tammergard.se/api/v1/to/abc")
// {
//   error: {
//     status: 400,
//     message: 'Invalid number "abc". Must be a positive integer.'
//   }
// }

Värden som har rätt form men är utanför tillåtet intervall – som ett arabiskt tal över 3999 eller en felformaterad romersk siffra som IIII – returnerar 422:

await fetch("https://roman.tammergard.se/api/v1/to/5000")
// {
//   error: {
//     status: 422,
//     message: 'Invalid number "5000". Must be between 1 and 3999.'
//   }
// }

Det är hela API:et. Det är byggt på paketet @tammergard/roman på npm.

roman.tammergard.se

Bakom API:et ligger en liten sajt på roman.tammergard.se. Där kan man konvertera mellan arabiska och romerska siffror, se dagens datum på latin, bläddra bland ettor, tiotal, hundratal och tusental, och öppna en egen sida för varje tal med grannar, dubblar och halvor.