98 lines
3.4 KiB
Markdown
98 lines
3.4 KiB
Markdown
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 |