1. 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

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

3. 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

4. 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

5. 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

6. (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

7. 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)

8. 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

9. About "New" Web Services: The Method
URL:
Method:
GetEmployee(int id)
The URL pattern is the method name, and the request parameters are the method parameters, hence the term Web API

10. 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

11. 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

12. 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

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

14. 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

15. 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.

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

17. 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”}

18. 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??

19. 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

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

21. 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

22. 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

23. 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 of ASP.NET Core in Action

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

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

26. 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

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

28. Readings
ASP.NET Core in Action: Chapter 9