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 e.g. /customers/	SPECIFIC ITEM 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

3.4 KiB Raw Blame History