# Ratkaisu- ja rajapintasuunnittelu

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

Language: fi

Entity ID: api-design

## Description

Suunnittele rajapintasopimus ja vuorovaikutusmalli sen jälkeen, kun arkkitehtuurivalinta on perusteltu.

## Why it matters

Kun arkkitehtuurimalli on tiedossa, suunnittelun on muutettava kyvykkyysvaatimukset selkeiksi rajapintasopimuksiksi, vuorovaikutuksiksi, skeemoiksi, datasäännöiksi, elinkaariodotuksiksi ja hyödyntäjien velvoitteiksi.

## Apply in work

Valitse valittuun toteutustapaan sopivat suunnitteluresurssit ja dokumentoi rajapintasopimus ennen toteutusta.

## Outcomes

- Validoitu rajapintasopimus valitulle toteutustavalle
- Johdonmukaiset vuorovaikutus-, data-, tapahtuma-, tiedosto-, työnkulku- tai API-rajapintasopimuspäätökset
- Suunnittelun jäljitettävyys kyvykkyyden ja hyödyntäjien vaatimuksiin
- Suunnitelmat linjassa toimialamallien ja vuorovaikutusmallien kanssa

## Steps

1. Käytä Domain Canvas -pohjaa uudelleen liiketoimintaolioiden, termien, sääntöjen ja omistajuuden vahvistamiseen ennen sopimussuunnittelua.
2. Kuvaa Interaction Canvas -pohjan avulla, miten hyödyntäjät, järjestelmät tai käyttäjät ovat vuorovaikutuksessa kyvykkyyden kanssa.
3. Käytä REST-suunnitteluresursseja, kun valittu rajapinta on REST API.
4. Käytä Event Canvas -resursseja, kun valittu rajapinta on tapahtumapohjainen.
5. Käytä GraphQL-suunnitteluresursseja, kun valittu rajapinta on GraphQL.
6. Käytä suunnitteluperiaatteita ja tyyliopasta, jotta suunnittelupäätökset ovat linjassa yhteisten sääntöjen kanssa ja auditointi voi validoida ne johdonmukaisesti.
7. Sovella contract-first- tai design-first-lähestymistapaa rajapintasopimuksen kuvaamiseen ja validointiin ennen toteutusta.
8. Käytä auditoinnin tarkistuslistaa varmistaaksesi, että suunnittelu täyttää toiminnalliset ja ei-toiminnalliset vaatimukset, mukaan lukien tietoturva, suorituskyky ja vaatimustenmukaisuus.

## Questions

- Käytä Domain Canvas -pohjaa uudelleen liiketoimintaolioiden, termien, sääntöjen ja omistajuuden vahvistamiseen ennen sopimussuunnittelua.
- Kuvaa Interaction Canvas -pohjan avulla, miten hyödyntäjät, järjestelmät tai käyttäjät ovat vuorovaikutuksessa kyvykkyyden kanssa.
- Käytä REST-suunnitteluresursseja, kun valittu rajapinta on REST API.
- Käytä Event Canvas -resursseja, kun valittu rajapinta on tapahtumapohjainen.
- Käytä GraphQL-suunnitteluresursseja, kun valittu rajapinta on GraphQL.
- Käytä suunnitteluperiaatteita ja tyyliopasta, jotta suunnittelupäätökset ovat linjassa yhteisten sääntöjen kanssa ja auditointi voi validoida ne johdonmukaisesti.
- Sovella contract-first- tai design-first-lähestymistapaa rajapintasopimuksen kuvaamiseen ja validointiin ennen toteutusta.
- Käytä auditoinnin tarkistuslistaa varmistaaksesi, että suunnittelu täyttää toiminnalliset ja ei-toiminnalliset vaatimukset, mukaan lukien tietoturva, suorituskyky ja vaatimustenmukaisuus.
- Valitse valittuun toteutustapaan sopivat suunnitteluresurssit ja dokumentoi rajapintasopimus ennen toteutusta.
- Kun arkkitehtuurimalli on tiedossa, suunnittelun on muutettava kyvykkyysvaatimukset selkeiksi rajapintasopimuksiksi, vuorovaikutuksiksi, skeemoiksi, datasäännöiksi, elinkaariodotuksiksi ja hyödyntäjien velvoitteiksi.

## Evidence

- spec
- contract
- design-artifact
- documentation

## Completion 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)

## 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.; suggested-answer-owner: [Kyvykkyysratkaisun suunnittelukanvas](https://apiopscycles.com/fi/resources/capability-solution-design-canvas.md)
- [Automaatiokehittäjä](https://apiopscycles.com/fi/roles/automation-engineer.md) (lead): Toteuttaa, testaa, integroi ja ylläpitää automaatioratkaisuja ja niitä tukevia työnkulkuja.; suggested-answer-owner: [Automaation työnkulkukanvas](https://apiopscycles.com/fi/resources/automation-workflow-canvas.md)
- [Integraatioarkkitehti](https://apiopscycles.com/fi/roles/integration-architect.md) (lead): Suunnittelee integraatiotavat ja toteutustavat, joilla kyvykkyys tai API yhdistetään muihin järjestelmiin.; suggested-answer-owner: [Integraatioratkaisun suunnittelukanvas](https://apiopscycles.com/fi/resources/integration-solution-design-canvas.md)
- [Alusta-arkkitehti](https://apiopscycles.com/fi/roles/platform-architect.md) (core): Ohjaa alustan, integraation, skaalautuvuuden ja arkkitehtuurin päätöksiä, jotka määrittelevät, miten kyvykkyys tai API rakennetaan ja operoidaan.
- [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.
- [Automaation omistaja](https://apiopscycles.com/fi/roles/automation-owner.md) (core): Vastaa automaation tavoitteista, liiketoiminta-arvosta, priorisoinnista, kontrolleista ja elinkaaren tuloksista.
- [Kyvykkyyden omistaja](https://apiopscycles.com/fi/roles/capability-owner.md) (core): Vastaa kyvykkyyden visiosta, arvosta, priorisoinnista, elinkaaresta ja uudelleenkäytöstä eri hyödyntäjille.
- [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.
- [Prosessin omistaja](https://apiopscycles.com/fi/roles/process-owner.md) (core): Vastaa automatisoitavasta liiketoimintaprosessista, mukaan lukien tavoitteet, säännöt, tulokset ja kehittämisen prioriteetit.
- [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.
- [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ää.

## Cycle-specific guidance

- [Kyvykkyyden tuotteistamisen sykli](https://apiopscycles.com/fi/cycles/capability-productization-cycle/stations/api-design.md)
- [API-tuotteistamisen sykli](https://apiopscycles.com/fi/cycles/api-productization-cycle/stations/api-design.md)
- [Integraatiokyvykkyyden tuotteistamisen sykli](https://apiopscycles.com/fi/cycles/integration-productization-cycle/stations/api-design.md)
- [Automaatiosykli](https://apiopscycles.com/fi/cycles/automation-cycle/stations/api-design.md)