# API-suunnittelu — API-tuotteistamisen sykli

Canonical page: https://apiopscycles.com/fi/cycles/api-productization-cycle/stations/api-design

Language: fi

Entity ID: api-design

Cycle: [API-tuotteistamisen sykli](https://apiopscycles.com/fi/cycles/api-productization-cycle.md)

Read [shared station guidance](https://apiopscycles.com/fi/stations/api-design.md) first. The sections below supplement or replace the corresponding shared sections for this cycle. Sections not repeated here retain the shared guidance.

## Journey entry criteria

- Kyvykkyys vastaa selkeään liiketoimintatarpeeseen ja on uudelleenkäytettävissä tarkoitetuille hyödyntäjille. — The API meets a clear business need and is reusable for multiple API consumers. (ID: api-reusability)
- Valittu rajapinta tarjoaa hyödyntäjille sopivan abstraktion. — The API is intended to shield consumers from backend complexity and inconsistencies. (ID: hide-backend-discrepancies)
- Kyvykkyyden arvolupaus on validoitu liiketoiminnan ja hyödyntäjien sidosryhmien kanssa. — The API value proposition has been reviewed and validated with the relevant business and consumer stakeholders. (ID: value-prop-validated)
- Hyödyntäjäsegmentit on tunnistettu. — API consumer segments (internal and external) are identified. (ID: consumer-segments-identified)
- Ylätason toteutuksen etenemissuunnitelma on määritelty. — High-level roadmaps for API development are established. (ID: api-roadmap-defined)

## Journey exit criteria

- Valittu arkkitehtuuri, alusta ja toteutustapa on validoitu olennaisten arkkitehtuuri-, tietoturva- ja alustasidosryhmien kanssa. — The chosen API architecture and platform patterns have been validated with the relevant architecture, security, and platform stakeholders. (ID: architecture-patterns-validated)
- Valittu rajapinta tarjoaa hyödyntäjille sopivan abstraktion. — The API is intended to shield consumers from backend complexity and inconsistencies. (ID: hide-backend-discrepancies)
- Rajapintasuunnittelu ja tarjottavat kyvykkyydet ovat jäljitettävissä liiketoiminta-arvoon ja hyödyntäjien tarpeisiin. — The API design and exposed capabilities clearly trace back to business value and user needs. (ID: design-reflects-business-value)
- Rajapintasuunnittelu noudattaa sovittuja suunnittelustandardeja ja käytäntöjä. — The API design follows our shared API product and design conventions. (ID: api-consistency)

## Description

Luo API-suunnitelmia, jotka ovat johdonmukaisia, uudelleenkäytettäviä ja perustuvat liiketoiminnallisiin tavoitteisiin sekä yhteisiin standardeihin.

## Why it matters

APIen suunnittelu ei tarkoita pelkästään päätepisteiden (endpoints) nimeämistä. Hyvä suunnittelu varmistaa, että APIt ovat käyttökelpoisia, johdonmukaisia ja linjassa liiketoiminnallisten ja teknisten tavoitteiden kanssa. Huono suunnittelu johtaa tiukkoihin riippuvuuksiin, heikkoon uudelleenkäytettävyyteen ja kalliiseen uudelleen toteutukseen eri tiimien välillä.

## Apply in work

Tarjoa uudelleenkäytettäviä suunnittelumalleja, yhteisiä standardeja ja validointityökaluja API-määrityksille. Varmista, että suunnittelupäätökset ovat johdonmukaisia, tarkistettuja varhaisessa vaiheessa ja linjassa liiketoiminnallisten tavoitteiden kanssa.

## Outcomes

- Hyvin dokumentoidut ja johdonmukaiset API-mallit
- Uudelleenkäytettävät ja validoidut API-sopimukset
- Toimialamallien ja vuorovaikutusmallien mukaiset mallit
- Suunnittelun jäljitettävyys liiketoiminnan arvoon

## Steps

1. Määrittele keskeiset oliot, niiden attribuutit ja suhteet yhteisen käsitteellisen ymmärryksen luomiseksi eri rajapinnoille.
2. Määrittele Interaction Canvasin avulla, miten hyödyntäjät ovat vuorovaikutuksessa APIn kanssa, ja Varmistetaan, että se vastaa heidän tarpeitaan ja odotuksiaan.
3. Sovellat REST-suunnittelumalleja luodaksesi johdonmukaisia, uudelleenkäytettäviä API-sopimuksia, jotka validoidaan sidosryhmien kanssa.
4. Sovellat tapahtumapohjaisia suunnittelumalleja luodaksesi johdonmukaisia, uudelleenkäytettäviä API-sopimuksia, jotka validoidaan sidosryhmien kanssa.
5. Sovellat GraphQL-suunnittelumalleja luodaksesi johdonmukaisia, uudelleenkäytettäviä API-sopimuksia, jotka validoidaan sidosryhmien kanssa.
6. Käytä suunnitteluperiaatteita ja API-tyyliohjetta, jotta suunnittelupäätöksesi ovat linjassa yhteisten sääntöjen kanssa ja mahdollistavat johdonmukaisen auditoinnin ja validoinnin.
7. Varmistetaan API-auditoinnin tarkistuslistan avulla, että API-suunnittelu täyttää toiminnalliset ja muut kuin toiminnalliset vaatimukset, mukaan lukien tietoturva, suorituskyky ja vaatimustenmukaisuus.
8. Käytä API-tarkastuslistaa varmistaaksesi, että API-suunnittelu täyttää toiminnalliset ja ei-toiminnalliset vaatimukset, mukaan lukien turvallisuus, suorituskyky ja vaatimustenmukaisuus.

## Questions

- Määrittele keskeiset oliot, niiden attribuutit ja suhteet yhteisen käsitteellisen ymmärryksen luomiseksi eri rajapinnoille.
- Määrittele Interaction Canvasin avulla, miten hyödyntäjät ovat vuorovaikutuksessa APIn kanssa, ja Varmistetaan, että se vastaa heidän tarpeitaan ja odotuksiaan.
- Sovellat REST-suunnittelumalleja luodaksesi johdonmukaisia, uudelleenkäytettäviä API-sopimuksia, jotka validoidaan sidosryhmien kanssa.
- Sovellat tapahtumapohjaisia suunnittelumalleja luodaksesi johdonmukaisia, uudelleenkäytettäviä API-sopimuksia, jotka validoidaan sidosryhmien kanssa.
- Sovellat GraphQL-suunnittelumalleja luodaksesi johdonmukaisia, uudelleenkäytettäviä API-sopimuksia, jotka validoidaan sidosryhmien kanssa.
- Käytä suunnitteluperiaatteita ja API-tyyliohjetta, jotta suunnittelupäätöksesi ovat linjassa yhteisten sääntöjen kanssa ja mahdollistavat johdonmukaisen auditoinnin ja validoinnin.
- Varmistetaan API-auditoinnin tarkistuslistan avulla, että API-suunnittelu täyttää toiminnalliset ja muut kuin toiminnalliset vaatimukset, mukaan lukien tietoturva, suorituskyky ja vaatimustenmukaisuus.
- Käytä API-tarkastuslistaa varmistaaksesi, että API-suunnittelu täyttää toiminnalliset ja ei-toiminnalliset vaatimukset, mukaan lukien turvallisuus, suorituskyky ja vaatimustenmukaisuus.
- Tarjoa uudelleenkäytettäviä suunnittelumalleja, yhteisiä standardeja ja validointityökaluja API-määrityksille. Varmista, että suunnittelupäätökset ovat johdonmukaisia, tarkistettuja varhaisessa vaiheessa ja linjassa liiketoiminnallisten tavoitteiden kanssa.
- APIen suunnittelu ei tarkoita pelkästään päätepisteiden (endpoints) nimeämistä. Hyvä suunnittelu varmistaa, että APIt ovat käyttökelpoisia, johdonmukaisia ja linjassa liiketoiminnallisten ja teknisten tavoitteiden kanssa. Huono suunnittelu johtaa tiukkoihin riippuvuuksiin, heikkoon uudelleenkäytettävyyteen ja kalliiseen uudelleen toteutukseen eri tiimien välillä.

## Role participation and responsibilities

- [API-suunnittelija](https://apiopscycles.com/fi/roles/api-designer.md) (lead): Suunnittelee rajapintasopimuksen, vuorovaikutusmallin, johdonmukaisuuden, käytettävyyden ja tarjottavat kyvykkyydet.
- [API-hyödyntäjien edustaja](https://apiopscycles.com/fi/roles/api-consumer-specialist.md) (core): Edustaa kehittäjien, integraattoreiden tai muiden API-hyödyntäjien tarpeita, jotka käyttävät APIa suoraan.
- [API-tuoteomistaja](https://apiopscycles.com/fi/roles/api-product-owner.md) (core): Ohjaa API-mahdollisuutta, priorisointia ja tuotetasolla tehtyjä päätöksiä elinkaaren aikana.
- [Liiketoiminta-asiantuntija](https://apiopscycles.com/fi/roles/domain-specialist.md) (core): Tuo syvällistä tietoa liiketoiminta-alueesta, käsitteistä, säännöistä ja rajoituksista, joita kyvykkyyden tai rajapinnan täytyy heijastaa.
- [Turvallisuusasiantuntija](https://apiopscycles.com/fi/roles/security-specialist.md) (core): Varmistaa, että turvallisuusriskit, kontrollit ja luottamusrajat käsitellään koko elinkaaren aikana.
- [Vaatimustenmukaisuus- ja lakiasiantuntija](https://apiopscycles.com/fi/roles/compliance-specialist.md) (core): Selventää juridiset, tietosuojaan liittyvät, sääntelyyn liittyvät ja sopimukselliset vaatimukset, jotka vaikuttavat kyvykkyyteen, APIin, rajapintaan tai automaatioon.
- [Alusta-arkkitehti](https://apiopscycles.com/fi/roles/platform-architect.md) (consulted): Ohjaa alustan, integraation, skaalautuvuuden ja arkkitehtuurin päätöksiä, jotka määrittelevät, miten kyvykkyys tai API rakennetaan ja operoidaan.
- [Dokumentoinnin ja kehittäjäsuhteiden omistaja](https://apiopscycles.com/fi/roles/api-devrel-specialist.md) (consulted): Varmistaa, että API-dokumentaatio, esimerkit, koulutus ja kehittäjäsuhteiden strategiat tukevat API-hyödyntäjien tarpeita.
- [Liiketoiminnan omistaja](https://apiopscycles.com/fi/roles/business-owner.md) (consulted): Edustaa liiketoimintatavoitteita, rahoitusta ja odotettuja tuloksia kyvykkyys-, API- tai automaatiohankkeessa.
- [Toimituskehittäjä](https://apiopscycles.com/fi/roles/api-engineer.md) (consulted): Vastaa toteutuksesta, automaatiosta, testauksesta ja julkaisun kulusta, joita kyvykkyyden, APIn tai automaation luotettava toimittaminen edellyttää.

## Resources

- [Vuorovaikutuskanvas](https://apiopscycles.com/fi/resources/interaction-canvas.md)
- [REST-kanvas](https://apiopscycles.com/fi/resources/rest-canvas.md)
- [Tapahtumakanvas](https://apiopscycles.com/fi/resources/event-canvas.md)
- [API-suunnitteluperiaatteet](https://apiopscycles.com/fi/resources/api-design-principles.md)
- [Toimialuekanvas](https://apiopscycles.com/fi/resources/domain-canvas.md)