RFC: API

[thewilkybarkid]

Problem

Libero needs to allow for services to read and modify data in other services.

Suggestion

• Use standard HTTP methods (GET, POST, PUT, DELETE) as a mechanism to read and modify content
• Adhere to HTTP, eg:
  • meaningful status codes
  • Content encoding negotiation
  • Language negotiation
• Use RAML to describe APIs
• Split entities into multiple endpoints, rather than having monolithic responses
  • eg separate article front matter, body, reference list
• Contract first rather than implementation
  • Allows replacement of implementations

Concerns

• RAML is an opinionated choice, but other existing options/standards don’t meet our requirements (eg OpenAPI)
  • eg OpenAPI is purely JSON focused, and doesn’t allow for composing schemas
• Doesn’t appear to be a way to actually use RAML during testing, which reduces its value a lot