Notes/UNB/Year 4/Semester 2/CS3103/2024-02-12.md

Lecture Topic: API Design
Special In person Lecture

# Web Services VS Web API
Network and Reusable
- Not libraries in the same app domain
- note one off custom integration
Two Broad categories
- Heavyweight, WS-* SOAP, WSDL
- Lightweight - HTTP, simple XML, or likely JSON

# REST
- Stateless - reduces complexity/ambiguity and improves scalability
	- No need to re-hydrate endpoints for new server state information
- Representations used for manipulation - create, update, etc
- Identifies in request example.com/api/contact/7
- Standard HTTP verbs
	- POST, GET, etc
- Proper response codes
	- i.e, 200 for success, 400 for missing, 500 for server issue

# HTTP Verb Debate
Easy to classify:
Request/query should be GET
Delete should be DELETE

More Debate:
Creates should be POST
Update can be PUT or PATCH but you should implement PATCH

HTTP Method Responce Codes

| HTTP VERB | CRUD           | ENTIRE COLLECTION <br>e.g. /customers/ | SPECIFIC ITEM <br>e.g. /customers/{id} |
| --------- | -------------- | ----------------- | ------------- |
| POST      | Create         | 201               | 404, 409      |
| GET       | Read           | 200               | 200, 404      |
| PUT       | Update/Replace | 405               | 200, 204, 404 |
| PATCH     | Update/Modify  | 405               | 200, 204, 404 |
| DELETE    | Delete         | 405               | 200, 404              |
# Some Libraries and Payloads
- Custom JSON
- OData
	- Started by Microsoft open source project, now OASIS
	- not strictly REST
	- JSON format standard for v4.0
	- Discoverability - Service and metadata document
- Json:api
	- JSON first
	- Very verbose - but better than XML
	- Hypermedia as the engine of application state (HATEOAS)

# Public, Partner, or Private APIs
Public: 
- Exposed to the internet, can be paid or require verification
- Documentation
Partner:
- More for internal usage between organisations
- Still need good documentation
Private:
- Mostly for yourself, but can often become one of the other category
- Not worrying about breaking data formats or changing routes
- Documentation not required

# Who are you building for
- Apps, IoT
- Other Sites
- Things not thought of yet
Try to think what it will be called from (smartphone, script, desktop application, other services)

# Table Stakes
## Authentication
Maybe try and use 3rd party libraries to handle authentication (OAuth)

Think about what your service will be called from, think tokens for service/script APIs or token/username password authentication for desktop apps or smartphone applications

## Analytics/Metrics
You need to know what people are asking for and creating to know what to build in the future
- Performance Degradation - Rate Limiting
- Monetisation - See what people are asking for and limits on free vs should be paid users

# Good Problems and Unintended Uses
Good problems:
- Large client
- Super popular app
Unintended uses
- Internal API sold to a customer - Business people selling what was an internal API and now are being required to support the internal API
- Reporting/Analytics
- Bulk data export - How do you get 100 records, 1000 records

Should think about when you should using something other than a REST API, if the requirements grow past what a REST API can reasonably support

# Living Documentation
Postman - getpostman.com
OpenAPI/Swagger
Hootsuite's API as an example (link)

# Recommendations
APIs - A strategy guide