Services | Application Programming Interface (API) Design
GET STARTED!REpresentational State Transfer (REST or “RESTful”) application programming interfaces (APIs) are one of the most important tools and technical design artifacts we have for documenting and utilizing system services and data. REST is a style, not a standard, so broad variations in REST can be found industry-wide.
| Term | Definition | Example |
| Business Entity | A person, place, or thing (noun) that information systems are intended to manage | |
| Resource | A data structure representing a Business Entity | |
| Collection | A sorted, paginated set of Resources, supporting both default and explicit set sizes | |
| Method | An HTTP operation that may be performed on a resource and that returns a standard response code and request body | POST (create), GET (read), PATCH (update) DELETE (delete) |
| URL | Uniform Resource Locator — a common or “base” path used with Methods to locate the Resources (or processes) managed by this API | |
| Endpoint | The final element added to the base URL to scope the request — should only contain plural Resources (nouns) or processes (verbs) but not Methods |
At a minimum, RESTful APIs must:
- Consistently follow RESTful style and best practices, e.g. RESTful API Design Guidelines — Best Practices, White House Web API Standards, etc
- Implement basic HTTP methods (see definition above) for low-level resource operations and the HTTP POST method for high-level process invocation
- Define structured resources as OAS 2.0 data input/output models in the definitions section to be used in HTTP request/response bodies
- Fully document attributes, security, endpoints, etc
- Include an API version (e.g. 1.0) in the URL
- Not go deeper than resource/{identifier}/resource
- Include elements that change the logic required to handle the response in the URL and elements that do not change the logic for each response, like OAuth info, in a header record
- Not use key values for property names
- Utilize JSON Web Tokens (JWT) for Base64Url encoding and cryptographic signing and encryption
Granular, well-structured APIs are also key enabler of vital business capabilities like business process modeling and A/B/n testing.
Let’s plan and document your organization’s APIs maximizing the ease with which then can be used to understand and leverage your valuable services and data!