Systematische Konstruktion von API-Verträgen

Systematische Konstruktion von API-Verträgen

Vortrag auf dem 280. Treffen der GI- / ACM- Regionalgruppe HH am

12.11.2014

Jan Christian Krause und Alexander Mills

Seite 2Seite 2Jan Christian Krause und Alexander Mills

Agenda

1. Einführung

Fallbeispiel

Grundbegriffe

Gestaltung von API-Verträgen

2. Identifikation von Lücken

3. Evaluierungsergebnisse

4. Automatisierte Lückenerkennung

5. Zusammenfassung


Einführung


Auswahl einer Verkaufsplattform (I)

• A1: Integrierbar in selbstentwickelte Systeme

• A2: Kundenbonität robust prüfbar

• Beschreibung unter http://developer.ebay.com/

„eBay Trading API“

Zugriff auf Operationen von eBay über HTTP

Bewertungssystem vorhanden (getFeedback())

Manipulierbar?

http://developer.ebay.com/


Auswahl einer Verkaufsplattform (II)

• Fachliche und technische Bezüge in Operationen

• Leistungsbeschreibung

• Bei Lücken drohen wirtschaftliche Konsequenzen

Wie können Inhalte dieser Beschreibung

systematisch abgeleitet werden?


Grundbegriffe


Prinzipien der Vertragsgestaltung

• … ist das schriftlich fixierte Verhandlungsergebnis zwischen

Anbieter und Benutzer einer Komponente.

• … schreibt fest, welche Leistung von der Komponente

unter welchen Bedingungen zu erbringen ist.

• … enthält Zusicherungen und Erwartungen.

• … wird geprägt durch das Geheimnisprinzip.

Ein Vertrag …


Qualitätskontrolle eines Herstellers

Hersteller

(im Kontext der Produktentwicklung)

Stille-Messgerät

Entsprechen meine

API-Verträge

meinen eigenen

Qualitätsansprüchen? API-Verträge

Prüfbericht

Habe ich die Bedingungen,

unter denen ich für die korrekte

Arbeitsweise meiner Komponente

bürge, klar genug eingegrenzt?


Qualitätskontrolle eines Auftragnehmers

Hersteller / Auftragnehmer

(im Kontext der Individualentwicklung)

Stille-Messgerät

Habe ich meinen Auftraggeber

verstanden oder muss

ich ihm weitere Fragen

stellen?

API-Verträge

Prüfbericht

Käufer /

Auftraggeber

API-Verträge

Fragen


Qualitätskontrolle eines Käufers

Käufer /

Auftraggeber

Stille-Messgerät

Kann ich auf Basis der

API-Verträge prüfen, ob die

Komponente meine Anforderungen

erfüllt? Falls nicht, welche Fragen

muss ich stellen?

API-Verträge

Prüfbericht

Hersteller

API-Verträge

Fragen

Arbeitet der

Hersteller sorgfältig?


Gewährleistung von Vollständigkeit

• Prüflistenbasierte Verfahren

• Quelltextbasierte Verfahren

Schrittweise, meist manuelle Vertragsprüfung

Statische Liste festgelegter Prüfkriterien

Automatische Vertragsprüfung

Quelltextanalyse (geworfene Ausnahmen,

Konfigurationen)


Identifikation von Lücken


Valenz eines Operationsbezeichners

• Beobachtung aus der Linguistik: Prädikate können

zusätzliche Angaben im Satz fordern (Valenz)

• Bezeichner von Operationen können Prädikate enthalten, z.B. computeFeedback()oder findCustomerById()

• Unser Ansatz: Rückschluss auf notwendige Vertragsinhalte

aus dem Prädikat des Bezeichners


Anwendung thematischer Raster (I)

Operation (Signatur + Vertrag):

public int computeFeedback(Long userId, Long itemId,

Long transactionId, Long orderLineItemId);

Thematisches Raster „Berechnende Operation“:

Compute

[OBJECT] [OPERAND] [FORMULA]

Belegtes Thematisches Raster

Compute[OBJECT FeedbackScore]

[OPERAND userId, itemId, transactionId, orderLineItemId]

[FORMULA ???]


Anwendung thematischer Raster (II)

/**

* Use this call to retrieve the accumulated feedback left for a specified user,

* or the summary feedback data for a specific item listing or order line item.

*

* @param userId [OPERAND]

* Specifies the user whose feedback data is to be returned. If not specified, then

* the feedback returned is for the requesting user.

* @param itemId [OPERAND]

* Unique identifier for an eBay item listing.

* @param transactionId [OPERAND]

* Unique identifier for an eBay order line item (transaction).

* @param orderLineItemId [OPERAND]

* OrderLineItemID is a unique identifier for an eBay order line item and is based

* upon the concatenation of ItemID and TransactionID, with a hyphen in between

* these two IDs.

* @return [OBJECT] Indicates the total feedback score for the user.

*

*

*

*/

public int computeFeedback(Long userId, Long itemId, Long transactionId, Long orderLineItemId);

OPERAND

OBJECT

FORMULA@formula See <a href=“…”>Introduction to Feedback</a>


Anwendung thematischer Raster (III)


Rasterbasierte Regeln

• Frage: Ableitung relevanter Inhalte aus bereits spezifizierten

thematischen Rollen?

• Beispiel: Sortierung im Fall mehrerer gefundener Kunden

• Ansatz: Rasterbasierte Regeln

Für jede Rolle eines Rasters existiert eine

prädikatenlogische Formel, die die Empfehlung der

Rolle steuert.

Mögliche Prädikate in dieser Formel sind:

exists(„ROLLE“)

isPlural(„ROLLE“)

isSingular(„ROLLE“)

hasAttributes(„ROLLE“)


Identifikation von Fehlerfällen

• Thematische Raster unterstützen bei der Ableitung von

Checked Exceptions.

• Wie soll das Programm reagieren, wenn eine

Rollenbelegung nicht verfügbar ist?


Evaluierungsergebnisse


Methodik

• Testfälle definieren die erwarteten Ausgaben einer

Operation bei bestimmten Eingaben.

• Repräsentativer Abbildung des Operationsverhaltens als

durch deren Signatur allein.

• Messung des Umfangs von Stille: Wie viele durch Testfälle

geforderte Ein- und Ausgaben sind im Vertrag enthalten?

• Messung der Relevanz von Stille: Wie viele Testfälle

beruhen auf den fehlenden Ein- und Ausgaben?


Versuchsaufbau

Operations-

signaturen

Probanden

modellieren

javadoc-

Konventionen

Katalog

Thematischer

Raster

Szenario

Definiert

Rahmenbe-

dingungen

Prüfliste nach Clements et al.

+ Satz einfacher Konventionen

Optimales Javadoc

Optimales Javadoc +

Thematische Raster

Erwartungshorizont

javadoc-

Konventionen

Vergleich

Vergleich

Systematisch

erzeugte

Testfälle


Umfang von Stille

0

1

2

3

4

5

6

7

8

9

10

Op. 1 Op. 2 Op. 5 Op. 16 Op. 6 Op. 7 Op. 8

An

zah

l Ein

ga

be

n

0

1

2

3

4

5

6

7

8

9

Op. 1 Op. 2 Op. 5 Op. 16 Op. 6 Op. 7 Op. 8

Erwartungshorizont

Optimales Javadoc

Optimales Javadoc + Thematische Raster

An

zah

l Au

sga

be

n

Op.1 = Lese Kundenaccount anhand der Kundennummer

Op. 2 = Prüfe Bonität anhand des Zahlungsverhaltens

Op. 16 = Speichere Bestellung

Op. 5 = Erzeuge Auftragsablehnung

Op. 6 = Berechne Rabatt

Op. 7 = Erstelle Rechnung

Op. 8 = Drucke und packe Rechnung


Relevanz von Stille

0

10

20

30

40

50

60

70

80

90

100

Op. 1 Op. 2 Op. 16 Op. 5 Op. 6 Op. 7 Op. 8

Optimales Javadoc Optimales Javadoc + Thematische Raster

An

teil

en

tsc

he

idb

are

rTe

stfä

lle in

%


Lessons learned

• Thematische Raster können den Umfang von Stille senken.

• Erkannte Eingaben: Von 54% auf 94%

• Erkannte Ausgaben: Von 51% auf 81%

• Die durch thematische Raster identifzierten Lücken sind

relevant.

Entscheidbare Testfälle: Von 62% auf 88%

• Quantifizierung dieser Verbesserung nicht allgemeingültig.


Automatisierte Lückenerkennung


Automatisierte Belegung thematischer Raster

Operation (Signatur + Vertrag):

public void copyFileAsciiToUtf(File input,

OutputStream output);

Thematisches Raster „Duplizierende Operation“:

Copy

[OBJECT]

[SOURCE] [DESTINATION]

[SOURCE_FORMAT] [DESTINATION_FORMAT]


Automatisierte Belegung thematischer Raster (II)

/**

* Copies bytes from an ASCII File to an OutputStream.

* The file will be converted from ASCII to UTF-8

* during this process.

*/

public void copyFileAsciiToUtf(File input, OutputStream output);


Copy

[OBJECT ???]

[SOURCE ???] [DESTINATION ???]

[SOURCE_FORMAT ???] [DESTINATION_FORMAT ???]


Automatisierte Belegung thematischer Raster (III)

/**

* Copies bytes from an ASCII File to an OutputStream.

* The file will be converted from ASCII to UTF-8

* during this process.

*/

public void copyFileAsciiToUtf(File input, OutputStream output);


Copy

[OBJECT bytes]

[SOURCE from an ASCII File] [DESTINATION to an OutputStream]

[SOURCE_FORMAT from ASCII] [DESTINATION_FORMAT to UTF-8]


Konzept für automatisierte Lückenerkennung

API-Vertrag

Operations-

bezeichner

Thematisches

Raster

Präpositional-

phrasen

Thematische

RollenBelegung des

Rasters

Fehlende

Belegung

=

Hinweis auf

Stille


Demonstration des Prototypen

C:/cygwin64/Presentation.bat

C:/cygwin64/Presentation.bat


Zusammenfassung und Ausblick


Zusammenfassung

• Aus Operationsbezeichnern können relevante Inhalte für

API-Verträge abgeleitet werden.

• Voraussetzung: Operationsbezeichner müssen

Konventionen genügen.

• Thematische Raster liefern Hinweise auf Lücken, bedürfen

aber der verantwortungsvollen Interpretation durch

Menschen.

• Bei Einhaltung bestimmter Konventionen zur Formulierung

können thematische Rollen teilweise automatisiert belegt

werden.


Vielen Dank für Ihre Aufmerksamkeit

Haben Sie Fragen?


Jan Christian Krause

Software-Entwickler

Mail [email protected]

Twitter @iDocIt

Blog idocit.blogspot.de

Github https://github.com/jankrause

Alexander Mills

Software-Entwickler

Mail [email protected]

Kontakt


Ausgewählte Literatur

• Paul Clements, Felix Bachmann, Len Bass, David Garlan, James Ivers, Reed Little, Robert

Nord und Judith Staord. Documenting Software Architectures - Views and Beyond. Addison-

Wesley Verlag, Boston u.a., 2003.

• Douglas Kramer. API Documentation from Source Code Comments: A Case Study of

Javadoc. In: (ohne Herausgeber) SIGDOC '99: Proceedings of the 17th annual

internationalconference on Computer documentation, Seiten 147 - 153, New York, 1999.

Association for Computing Machinery.

• Oracle Corp. How to Write Doc Comments for the Javadoc Tool, ohne Jahr. Dieser Artikel ist

unter http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html

verfügbar (letzter Abruf am 15.03.2013).

• David Lorge Parnas. Information distribution aspects of design methodology. In: C.V.

Freiman, J.E. Grith und J.L. Rosenfeld (Hrsg.), Information Processing 71 - Proceedings of

the IFIP Congress 71, Band 1, Seiten 339 - 344, Amsterdam, London, 1971. North Holland

Publishing Company.

• David Lorge Parnas. On the Criteria To Be Used in Decomposing Systems into Modules.

Communications of the ACM, Band 15 (Ausgabe 12): Seiten 1053 - 1058, 1972.

• Jan Christian Krause. Vermeidung von Lücken in API-Verträgen. Dissertation, Universität

Hamburg, 2014. Diese Dissertation ist unter http://ediss.sub.uni-

hamburg.de/volltexte/2014/7022 verfügbar (letzter Abruf: 13.11.2014).

http://ediss.sub.uni-hamburg.de/volltexte/2014/7022


Die 10 häufigsten Verben des seekda-Korpus

Rang Verb Häufigkeit

1. get 74.790

2. add 6.105

3. create 4.929

4. delete 4.769

5. update 4.398

6. send 3.176

7. list 2.658

8. check 1.944

9. remove 1.861

10. is 1.845


Thematische Raster

Prüfende Operation Parsende Operation

Schlussfolgernde Operation Deponierende Operation

Konvertierende Operation Löschende Operation

Erzeugende Operation Rücksetzende Operation

Beschreibende Operation Suchende Operation

Duplizierende Operation Sendende Operation

Verbindende Operation Initiierende Operation

Lesende Operation Substituierende Operation

Protokollierende Operation Traversierende OPeration

Berechnende Operation Zusammenführende Operation


Evaluierung des Prototypen

33%

21%18%

28%

Gefundene Lücke Gefundene Belegung

Nicht gefundene Belegung Nicht gefundene Lücke


Fehlerklassifikation des Prototypen

41%

8%16%

35%

Rolle nicht mit Präposition erkennbar

Falsche Belegung ausgewählt

Fälschlicherweise als Lücke erkannt

Lücke nicht erkannt


Schwächen des Prototypen

• Viele thematische Rollen teilen sich gemeinsame

Präpositionen

• Fehler des NL-Parsers bei Imperativsätzen

• Viele thematische Rollen nicht durch Ansatz belegbar (z.B.:

FORMULA, OPERAND)

• Autor des API-Vertrags muss „Kochrezept“ befolgen damit

Trefferrate möglichst hoch ist


Empfehlungen zur Formulierung

Thematische Rollen (bewusst) durch Präpositionen einleiten

Richtig:

grep searches lines in the named input FILEs

Falsch:

grep searches the named input FILEs for lines


Empfehlungen zur Formulierung (II)

Kurze und prägnante Sätze formulieren

Richtig:

Reads a set of customer data from a

database. The customer data is filtered by

the given name and then ordered by id.

Falsch:

Reads a set of customer data with the given

name from a database ordered by id.


Empfehlungen zur Formulierung (III)

Thematischen Rollen so früh wie möglich belegen

Returns data from a file...

...

...

Get more information from https://...

Get more information from https://...

...

...

Returns data from a file...

Systematische Konstruktion von API-Verträgen

Software

Transcript of Systematische Konstruktion von API-Verträgen