Käytännöt

API-käytännöt

Miten Data API versioidaan, miten poistumisista ilmoitetaan ja kuinka kauan ne kestävät, ja miten tietoturvahavainnosta ilmoitetaan.

Versiointi

API versioidaan polussa: jokainen päätepiste löytyy osoitteesta /api/v1. Sopimuksen info.version (tällä hetkellä 1.3.1) noudattaa muutoslokia: pieni numero kasvaa, kun jotain lisätään, korjausnumero silloin kun jotain korjataan, ja uusi polkuversio (/api/v2) on ainoa tapa julkaista rikkova muutos.

Kahdeksan virallista SDK-kirjastoa seuraa rajapintaa: uusi päätepiste on SDK-kirjaston pieni julkaisu, poistettu tai uudelleennimetty suuri julkaisu.

Mikä lasketaan rikkovaksi

Näitä ei tapahdu koskaan polkuversion sisällä:

• Päätepisteen, kyselyparametrin tai vastauskentän poistaminen tai uudelleennimeäminen.
• Kentän tietotyypin muuttaminen tai se sääntö, että hinnat, kurssit ja määrät ovat desimaalimerkkijonoja.
• { data, meta } -kuoren, virhekuoren tai olemassa olevan virhekoodin merkityksen muuttaminen.
• Suunnitelmaan jo kuuluvan nopeusrajan tai kvootan laskeminen.

Näitä voi tapahtua milloin tahansa, ja niistä ilmoitetaan muutoslokissa:

• Uudet päätepisteet, kyselyparametrit ja vastauskentät.
• Uudet virhekoodit uusiin tilanteisiin – vertaa aina kenttään error.code, älä koskaan viestiin.
• Uudet arvot listoissa, joiden referenssi kertoo voivan kasvaa, kuten tapahtumien ja indikaattorien nimet.
• Korkeammat rajat ja kvootat.

Poistuminen

Kun päätepiste, parametri tai kenttä on määrä poistaa, siitä ilmoitetaan muutoslokissa ja sähköpostilla jokaiselle avaimen haltijalle, ja samasta päivästä alkaen päätepiste vastaa Deprecation- ja Sunset-otsakkeilla (RFC 9745, RFC 8594), jotka kertovat poistopäivän. OpenAPI-sopimus merkitsee sen kentällä deprecated: true.

Poisto tapahtuu aikaisintaan kuusi kuukautta ilmoituksen jälkeen. Uusi polkuversio toimii edellisen rinnalla vähintään kuusi kuukautta, ennen kuin vanha poistuu samalla tavalla.

Rajat ja kohtuullinen käyttö

Minuuttikohtaiset purskerajat ja kuukausikvootat kuuluvat suunnitelmaasi, ne raportoidaan joka vastauksessa otsakkeissa X-RateLimit-* ja X-Quota-* ja ne on dokumentoitu referenssissä. Rajan nostaminen ei ole koskaan rikkova muutos; sen laskeminen suunnitelman sisällä on, ja se noudattaa poistumisaikataulua.

Vastuullinen ilmoittaminen

Jos uskot löytäneesi tietoturva-aukon sivustolta bitculator.com, Data API -rajapinnasta, MCP-palvelimesta tai SDK-kirjastoista, lähetä sähköpostia osoitteeseen contact@bitculator.com ja kerro mikä osoite tai päätepiste on kyseessä, miten se toistetaan ja mikä vaikutus siitä seuraa. Vastaamme kolmen työpäivän kuluessa.

Pidä ilmoitus yksityisenä, kunnes vika on korjattu, älä käsittele tai muuta dataa joka ei ole sinun, äläkä aja palvelunestohyökkäyksiä tai automaattista skannausta tuotantoa vastaan. Vilpittömässä mielessä näiden ehtojen mukaan tehdyistä ilmoituksista ei seuraa oikeustoimia. Maksettua palkkio-ohjelmaa ei ole; maininta annetaan pyynnöstä.

Sama yhteystieto on julkaistu koneluettavasti osoitteessa /.well-known/security.txt (RFC 9116).

Tila ja häiriöt

Komponenttien tila reaaliajassa, avoimet häiriöt ja viimeisten 30 päivän katkokset löytyvät tilasivulta ja osoitteesta /status.json.