Chengyu Sun California State University, Los Angeles CS4540 Special Topics in Web Development ASP.NET Core: Design and Implement Web API Chengyu Sun California State University, Los Angeles

Web API A.K.A. RESTful/REST Web Service RESTful/REST Web API REST API

A Brief History of Web Service Remote Procedure Call Simplifies network programming RPC CORBA Cross-platform RPC (Traditional) Web Services Cross-platform RPC over HTTP SOAP – complex and not efficient RESTful Web Services

RPC – Client-Server Interaction as Function Calls Employee e = GetEmployee(1); Automatically translate function calls to network operations Encode and decode parameters and return values Send and receive data between the client and the server Employee GetEmployee(int id) { … return employee; } Server

CORBA Common Object Request Broker Architecture Use Interface Definition Language (IDL) to describe service interface Provide mappings from IDL to other languages such as Java, C++, and so on. Java Service Interface in IDL Service Implementation C++ … Client Server

(Traditional) Web Services RPC over HTTP Client and server communicate using HTTP requests and responses Traditional web service stack SOAP for data exchange WSDL for API description UDDI for web service directories

Problems With Traditional Web Services Very complex Based on some very complex specifications Very difficult to create supporting libraries Virtually impossible to use without supporting libraries Not very efficient (XML is a very verbose language)

Mimic a Web Service Without All the Trouble Traditional Web Service Call GetEmployee(1) Some magic happens Get an Employee object Client Server "New" Web Service Send a request to /Employees/1 Get a response Convert the response to an Employee object Client Server

About "New" Web Services: The Method URL: http://<host>/Employees/{id} Method: GetEmployee(int id) The URL pattern is the method name, and the request parameters are the method parameters, hence the term Web API

About "New" Web Services: The Return Value In "New" Web Service, it's now the client's responsibility to convert the response into an object, which is why the response is usually in JSON and/or XML

About "New" Web Services: The Benefit Now any web application language/technology can be used to create web services, which are basically web applications for programs In particular, it's the same MVC minus V

REST – Make "New" Web Services Better REpresentational State Transfer Introduced by Roy Fielding in his Ph.D. dissertation on network-base software architecture Describes the common characteristics of scalable, maintainable, and efficient distributed software systems

The REST Constraints Client and server Stateless Support caching Uniformly accessible Layered (Optional) support code-on-demand

RESTful Web Services Mimic how the static web (i.e. the largest REST system) works Use URLs that look like URLs for static web pages Utilize request methods and headers Utilize response status codes Stateless, i.e. no session

RESTful Web Service Design Identify resources and operations Determine resource representation, i.e. JSON and/or XML Design the "API" (a.k.a. end points), i.e. URL patterns, request methods/parameters/headers, etc.

Web API Design Conventions Route parameters over query parameters Map request methods to CRUD operations POST GET PUT DELETE Create Retrieve Update Delete

Web API Design Example (I) Operation HTTP Request Get a project GET /projects/1 HTTP 1.1 Delete a project DELETE /projects/1 HTTP 1.1 Update a project PUT /projects/1 HTTP 1.1 { "id": 1, "name": "Firestone2”}

Web API Design Example (II) Operation HTTP Request Get all project GET /projects HTTP 1.1 Add a project POST /projects HTTP 1.1 { "name": "Yellow", "leaderId": 2,} How about adding/removing an employee to/from a project??

Web API Implementation Example Project management Get all projects Get a project by id Add an employee to a project Remove an employee from a project

Example: Get All Projects Controller vs. ControllerBase Attribute Routing vs Conventional Routing Serialization and De-serialization Content negotiation

Attribute Routing vs. Conventional Routing Web API usually use attribute routing because the action is usually expressed in request method rather than the URL Attribute routing takes precedence over conventional routing

Serialization and Deserialization Object XML/JSON De-serialization ASP.NET Core applications use JSON formatter by default Additional formatters can be added with additional packages

Content Negotiation The format of the data is determined by Accept header example: Accept: application/json,text/xml;q=0.9 The format of the data is determined by The accept header The object itself Whether the client is a browser See Chapter 9.6.2 of ASP.NET Core in Action

Example: Get A Project By Id Use of status codes and helper methods in ControllerBase Ok() NotFound()

Example: Add an Employee to a Project Add an object to a many-to-many collection Test Web API using Postman

Example: Remove an Employee from a Project Remove an object from a many-to-many collection Use JavaScript in a web application as Web API client @section jQuery

Web API Clients Web API Server Web Applications Mobile Apps Desktop Other Web Services

Readings ASP.NET Core in Action: Chapter 9