Understanding and Documenting Web APIs

Transcription

1 Understanding and Documenting Web APIs tekom 2017, Stuttgart, Germany Oct Anne Tarnoruder SAP Labs Israel Ltd.

2

3 Part 1. Understanding Web APIs 8:45-9:30 Break 9:30-9:45 Part 2. Documenting Web APIs 9:45-10:15 Q&A 10:15-10:30

4 A little recap of school mathj What is a function? Takes an input (argument) X Does something with it Returns an output (value) Y X(Input) F (Function) Y (Output) Software code is a collection of functions. Software works by performing function calls. Functions can be reused.

5 Save time, effort and costs of development Avoid implementing repeated tasks Focus on core functionality Make own code available to others, monetize it

6 Cut n paste techniques (early days ~ 1980s) Code libraries, DLLs (~late 1980s) Object-Oriented Programming (~early 1990s) Code chunks copied from program to program Easy to do Difficult to maintain Libraries of functions bundled with applications Private and proprietary Limited usage Still exist (e. g. Windows) Components as black boxes Component object model (COM, CORBA) Client-server model

7 What is a black box? In science, computing, and engineering, a black box is a device, system or object which can be viewed in terms of its inputs and outputs, without any knowledge of its internal workings. Its implementation is "opaque". Wikipedia function component black box Exposes inputs and outputs (interface) Performs processing Hides implementation Input Input Output Output Client programs can call the functions of the component Clients need to know only the interface

8 Component interface is a collection of data and functions exposed by component to clients Field: a data item defined by name and type Method: a function defined by name, input parameters (arguments) and output (return value ) The Order component has some fields and methods that allow to add or edit an order in the system. A client application can call the methods of an interface. It doesn t need to know how the methods are implemented.

9 API (Application Programming Interface) can mean: A single method. The interface (all methods) of a single component. A package of related interfaces. API is a contract: once published, cannot be broken. If changed without notice, client apps will not work as expected. To change an API, a deprecation mechanism is used. API is only as good as its documentation: Has no visual interface. No simple way to figure it out without documentation.

10 Client Side Server Side Client Client Client App App App Service Component Network API calls as request/response messages Main Principles Client and server components are distributed over the same network. Server components expose APIs which clients can call. Clients and servers exchange request-response messages. Implementations based on industry standards: COM/DCOM, CORBA, RPC, ActiveX Drawbacks Client and server components have to be on the same network and be implemented in the same language. Tightly-coupled integration. Limited interoperability. Network constraints.

11 SOAP Web services (~early 2000s) Perform any API calls over HTTP Use standard protocols (SOAP, WSDL) Platform- and network independent Relatively complex to produce and use RESTful Web services/apis (mid-2000s and on) RESTful (Representational State Transfer) Web services Lightweight alternative to SOAP Perform fixed operations Simpler to produce and use Growing popular in the recent years

12 Discovers WSDL UDDI (Universal Discovery Registry) Publishes WSDL WSDL Client App Service Provider Client Client Client App App App Service Component API calls as HTTP request/response messages

13 Web Service Benefits Is a collection of related service components that provide their APIs over the Web to client apps independently of their platform and implementation, using standard communication protocols and standard publication and discovery mechanisms. Availability over the Web Platform and language independence Drawbacks Impact on performance Relative complexity of implementation and usage

14 A Create, Read, Update, Delete operation performed on data. An HTTP request sent to the data resource s URI. RESOURCE: A remote data entity, identified by a URI, on which a CRUD operation is performed. Client App Client App Client App C/R/U/D HTTP Request XML/JSON HTTP Response Service Provider Service Component An HTTP response sent to client app in standard format (XML/JSON).

15 REST APIs a.k.a. RESTful Web Services The Benefits of REST are Web-based APIs that perform CRUD operations on data resources over the Web by sending HTTP method requests to resource URIs and receiving HTTP responses in a standard format. Fixed operations Standard HTTP communication Simple to understand and use

16 What are REST Clients? Rich UI tools for interactive running and testing REST APIs. Freely available as Chrome apps and standalone desktop apps. Popular: Postman, Advanced REST Client, Insomnia, DHC Rest Client. Why should I use them? To explore the APIs that you are documenting. To get the information that you aren t getting from developersj. Demo Use Postman to perform some API calls

17 Combination of host and resource path

18

19 OData Protocol A standard protocol for the description of data models and interacting with data via REST interfaces. OData Service Exposes data sources to clients via the OData data model. OData APIs Enables clients to access the data by REST calls. REST APIs to access data sources exposed by OData services. Documented similarly to REST APIs. More information: Introducing OData (MSDN)

20 OData Service Sends REST operation request to resource Resource URIs Provide access to data Entity Data Model Exposes data entities from DB Client App Client App Client App customerid}/orders Entity Product Entity Order Entity Customer Database

21

22

23 API Documentation Deliverables Swagger /OpenAPI Specification Demo: Using Swagger Editor Other API Formats and Frameworks

24

25

26 Swagger OpenAPI Initiative (OAI)

27 apihandyman.io OpenAPI Specification Visual Documentation Tutorials

28 YAML definition file in the editor Generated output

29

30 Pros Rich and comprehensive spec that allows to describe various aspects of APIs. Has an appealing interactive output. Fully open-source solution. Heavily adopted, has a large ecosystem of users and supporters. Cons Good for simple and small APIs, but difficult to manage complex and large APIs. To use it, you need to know the specification well. Working directly in the Swagger editor is tiresome and error-prone. Difficult to integrate output in a developer guide.

31 RESTful API Modeling Language

32 The API Designer provides a web-based graphical environment for designing, documenting, and testing APIs in the RAML and OAS formats. Collaborative design, instant API mock, generated documentation, integrated code samples, debugging and automated testing, supporting the API Blueprint and OAS formats. Allows you to create and load API designs in OAS and RAML formats, and generate client side SDKs in multiple languages. Integrated products covering an entire API lifecycle, including visual design, hosted documentation, and testing APIs. OAS and RAML format support.

33 Pros Single source of truth Output is cool and interactive Documentation gets updated with code Developers are responsible for its maintenance and production Work processes are easier Cons Where do I document other aspects of APIs concepts, diagrams, how-to, scenarios, security etc.? How do I integrate API references with developer guides? What if auto-generation is not available for my project API is very new or too small, no infrastructure set up, no budget, tight deadlines etc.? I m not comfortable with writing in a coding environment My API guide is scenario-oriented, reference format doesn t quite fit in

34 Write API reference topics within your developer guide, and organize them as required. Complement with conceptual, howto, security information, diagrams, examples etc. To ensure the consistency of look and feel, and completeness of information, consider using templates for the reference topics.

35 Questions? Thank you!

36 Your opinion is important to us! Please tell us what you thought of the lecture. We look forward to your feedback via smartphone or tablet under or scan the QR code >>>>>> The feedback tool will be available even after the conference!