API Documentation. Web Application Development. Zsolt Tóth. University of Miskolc. Zsolt Tóth (University of Miskolc) API Documentation / 28

Transcription

1 API Documentation Web Application Development Zsolt Tóth University of Miskolc 2018 Zsolt Tóth (University of Miskolc) API Documentation / 28

2 Data Transfer Object Data Transfer Objects Bean Information Hiding Remove Sensitive Data Account Number IDs Reduction of Network Traffic Complex Data Structures Standard Communication Openness Text Based Data Formats XML JSON Platform Independent Server Client Java, C#, PHP REST API SOAP HTML, JavaScript, AJAX Web Service Service-to-Service Desktop Application Zsolt Tóth (University of Miskolc) API Documentation / 28

3 Data Transfer Objects DTO vs POJO DTO Data Structure Bean Complex Marshalling POJO OOP Information Hiding Inheritance Business Logic Zsolt Tóth (University of Miskolc) API Documentation / 28

4 Data Transfer Objects Request/Response Objects Different Data Structures Requests / Responses per Recording Service Challenges Flexibility Mandatory and Optional Fields Bean Default Constructor Public getter/setter Methods In Controller Only! Data Formats Binary (server side) XML (schema validation) JSON (compactness) Automatic Conversion Marshalling Object Text Text Object Multiple Formats Transformations JSON XML Schema Definition / Validation Zsolt Tóth (University of Miskolc) API Documentation / 28

5 Data Transfer Objects Generation XJC tool, application XSD Annotated Java Class Maven jaxb2-maven-plugin Tags packagename sources Location /target/ generated-sources Ignore Version Control! XSD Complex Types Schema Validation Data Types Generated Beans XML Mapping JSON Mapping jackson Parser Zsolt Tóth (University of Miskolc) API Documentation / 28

6 Table of Contents REST API Documentation 1 Data Transfer Objects 2 REST API Documentation 3 WSDL Zsolt Tóth (University of Miskolc) API Documentation / 28

7 REST API Documentation REST API Types of Web Services REST API Simple JSON Messages Currently popular Web Service WSDL XML SOAP Zsolt Tóth (University of Miskolc) API Documentation / 28

8 REST API Documentation REST Documentation From developers to developers Openness Service Integration Interface Definition Acceptance Test Recommended Structure Title URL Pattern Method URL Parameters Body Parameters Successful Response Error Response Request example Notes Zsolt Tóth (University of Miskolc) API Documentation / 28

9 REST API Documentation Title Short Descriptive Define the service Type Purpose Count Sort description is optional 1 List Measurements type Query / Fetch purpose clear count many records 2 Record Measurements type recording purpose understandable count single record 3 Query Measurement number of record is not defined Zsolt Tóth (University of Miskolc) API Documentation / 28

10 REST API Documentation URL Pattern Location of the service Path only Unnecessary Server Port Application URL Mapping web.xml Parameters /measurements /measurements/:id Zsolt Tóth (University of Miskolc) API Documentation / 28

11 REST API Documentation Method HTTP Method Single URL Multiple Methods Single URL Multiple Services Different Method Different Behavior /measurement/:id GET Query a single record by id. POST Record of modify a record with the given id. Zsolt Tóth (University of Miskolc) API Documentation / 28

12 URL Parameters REST API Documentation GET Method Query Parameters Key Value Pairs Mandatory or Optional Expected Value Number Text Date (Format) URL Encoding Zsolt Tóth (University of Miskolc) API Documentation / 28

13 Body Parameters REST API Documentation POST Method JSON Structure Definition Data Structure Restriction Data Transfer Object Zsolt Tóth (University of Miskolc) API Documentation / 28

14 REST API Documentation Successful Response Status Code Response Body HTML JSON Structure description (JSON) Zsolt Tóth (University of Miskolc) API Documentation / 28

15 Error Response REST API Documentation Many different errors Different error, different status codes Using existing HTTP Status Codes Additional meaning Error Message Structures JSON Typical Errors Permission Unexpected Parameters Service unavailable Validation or Sanitize Error Zsolt Tóth (University of Miskolc) API Documentation / 28

16 Example Request REST API Documentation Executable format curl AJAX Facilitate the usage Easy to understand Zsolt Tóth (University of Miskolc) API Documentation / 28

17 REST API Documentation Notes Explanation of ambiguous parts. Faults and fixes documentation. Versioning Suggestion Timestamp Author Note Zsolt Tóth (University of Miskolc) API Documentation / 28

18 WSDL Table of Contents 1 Data Transfer Objects 2 REST API Documentation 3 WSDL Zsolt Tóth (University of Miskolc) API Documentation / 28

19 WSDL Web Service Description Language W3C 2007 XML XSD Platform Independent Text Based Semi Structured Automatic Processing Code Generation Service Abstract Types Messages Ports Implementation URL, port Class Zsolt Tóth (University of Miskolc) API Documentation / 28

20 WSDL Web Service Description Language Zsolt Tóth (University of Miskolc) API Documentation / 28

21 WSDL WSDL Structure <definitions> <types>definition of types...</types> <message>definition of a message...</message> <porttype> <operation>definition of a operation...</operation> </porttype> <binding>definition of a binding...</binding> <service>definition of a service...</service> </definitions> Zsolt Tóth (University of Miskolc) API Documentation / 28

22 WSDL Type Definition types tag XML Schema Definition Simple Types Text Number true, false Restrictions RegEx Enumeration Interval Complex Types Arrays, Lists Objects <types> <schema targetnamespace = "..." xmlns = "..."> <element name = "..."> <complextype>... </complextype> </element> </schema> </types> Zsolt Tóth (University of Miskolc) API Documentation / 28

23 WSDL Message Definition Request/Response Messages Name Complex Structure Data Transfer Object Types input output Messages Parts <message name = "SayHelloResponse"> <part name = "greeting" type = "xsd:string"/> </message> Zsolt Tóth (University of Miskolc) API Documentation / 28

24 WSDL Port Definition End Point of the Web Service Name Type One-way Request Response Solicit Response Notification Messages Order input output fault Zsolt Tóth (University of Miskolc) API Documentation / 28

25 WSDL One-Way, Request-Response One-Way Service waits for Request No Response Only input HTTP 202 OK Response Request-Response Clint sends Request and wait for Response input and output HTTP Zsolt Tóth (University of Miskolc) API Documentation / 28

26 WSDL Solicit-Response, Notification Solicit-Response Server sends data Client sends Ack. Inverse behavior output and input definition Notification Szerver sends data Client does not send Ack Only output Broadcasting Zsolt Tóth (University of Miskolc) API Documentation / 28

27 WSDL Binding Definition Definition of the Implementation porttype Data Transfer GET, POST Simple Object Access Protocol Single porttype multiple binding binding name port Zsolt Tóth (University of Miskolc) API Documentation / 28

28 WSDL Service Definition End Point Definition Assign binding to Class Single Service may have multiple port. Where is the service? Via which port can it be accessed? Messages? Concrete URL Zsolt Tóth (University of Miskolc) API Documentation / 28