Let's communicate...

HTTP

• Well-known concepts
• Extremely well supported
• Least Common Denominator

REST

• Stateless req / res pattern
• Endpoint = path, method
• Request = path, method, headers, body
• Response = statusCode, headers, body

More Specifically

• Paths are nouns, represent resources
• Methods are verbs, represent actions
• Status codes, headers have meaning

More MORE Specifically

• I DONT KNOW STOP PRESSURING ME

THE API SPEC!

Secured!

• Always HTTPS
• Ship self-signed certs
• Allow customers to provide

Style guide

• All endpoints support JSON
• CamelCase
• Use GUIDS for IDs
• Dates: ISO-8601
• createdOn, modifiedOn, createdBy, updatedBy
• Return full, unwrapped representations
• No custom HTTP verbs
• Custom actions always live under /actions

Headers

• Authentication is required
• Accepts for versioning. Default to v1.
• Respect Content-Type. Default to JSON.
• E-Tag for caching.
• Request-Id
• Request-Origin-Date

Protect Yourself

• Input validation with useful feedback
• Rate Limiting
• Drop stale requests

Self-Documenting

• OPTIONS requests on each endpoint
• Protos for input / output
• List supported methods & child routes

Errors!!!

The Well-Behaved Error

• All Services return exactly one error format
  • statusCode
  • name
  • message
  • messageCode
  • source
  • details
  • upstreamError
• ​Can strip technical details based on client ID

This is a lot of work...

For Engineering

• "The Public" vs "The Other Team" 
• Everything is an integration
• Time reading & using vs writing

For the Business

• Use your dev resources better
• You can expose your APIs. So DO!
• Interface possibilities