From cc462161fd29448416fec72a73dcaf978320328f Mon Sep 17 00:00:00 2001 From: Yusuke Tsutsumi Date: Wed, 24 Jan 2024 09:08:05 -0800 Subject: [PATCH] addressing comments. --- aep/general/0005/aep.md | 65 ++++++++++++++++++++++++----------------- 1 file changed, 38 insertions(+), 27 deletions(-) diff --git a/aep/general/0005/aep.md b/aep/general/0005/aep.md index 25a8bfa9..62321015 100644 --- a/aep/general/0005/aep.md +++ b/aep/general/0005/aep.md @@ -1,29 +1,35 @@ # Designing an API -This AEP serves as a high-level guide on designing an API that adheres to the +This AEP serves as a high-level guide to designing an AEP-compliant API. AEPs. ## Process summary -1. enumerate the user case would like your API to satisfy. -1. identify resources and add them to your API. -1. identify standard operations and add them to your API. -1. identify custom operations and add them to your API. +1. Enumerate the use cases you would like your API to satisfy. +1. Identify resources. +1. Identify standard operations. +1. Identify custom operations. ## Enumerate use cases -The first step in designing an API is understanding precisely what you would -like your user to be able to accomplish your API. +The first step in designing an API is understanding precisely what operations +you would like your user to perform. Enumerate these operations, attempting to +be as granular as possible. -Enumerate one or more use cases to clarify what precisel - -For example: +For example, if the API is for VM management in a public cloud, the operations +may include: - Create a VM. - List all VMs owned by a company. - List all VMs owned by a user. - Restart a running VM. -- Trade an in-game item with another player. + +Or for a multiplayer online game, operations may include: + +- Proposing a trade to another player. +- Accepting a proposed trade. +- Find open trade offers containing an item. +- List items in a player's inventory. Some best practices: @@ -32,29 +38,33 @@ Some best practices: ## Identify resources -Once your use cases are defined, consider how many of those can be accomplished -by represented by an [API Resource Type][]: similar to object-oriented -programming, these are use cases that can be represented by entities that are -created, read, updated, and deleted. +Once your use cases are defined, consider how many of those can be represented +by an [API Resource Type][]: entities that are created, read, updated, and +deleted. Examples include: - users -- virtual machine +- virtual machines - load balancers - services -The core of the AEPs is resource-oriented design: this design paradigm allows -for uniform standard operations that reduce the cognitive overhead in learning -about the operations and schemas exposed by your API. +One of the core concepts described by the AEPs is resource-oriented design: this +design paradigm allows for uniform standard operations that reduce the cognitive +overhead in learning about the operations and schemas exposed by your API. + +Resources can relate to each other. For example: -Resources can relate to each other, either as a parent-child relationship -defining ownership, or via references that defines the resources usage of -another resource in it's operations (e.g. a vm depending on a private network). +- A parent-child relationship defining ownership/scope (A user who created a + VM). +- A resource dependency, where one resource depends on another to function (A VM + depending on a disk). See the following AEPs to learn more about resource-oriented design: +- [resource-oriented design][AEP-121] - [resource paths][AEP-122] +- [resource types][AEP-123] ## Identify standard operations @@ -70,12 +80,13 @@ See the following AEPs to learn more about the standard operations: ## Identify custom operations -To accomplish some of the user journeys, resources may need to support more -than just operations to create, read, update, delete, and list them. Some -examples include: +To accomplish some of the user journeys, resources may need to support +operations other than [Create][AEP-133], [Update][AEP-134], [AEP-135][Delete], +[AEP-131][Get], and [AEP-132][List] them. Some examples include: -- restarting a virtual machine. -- cleaning a disk. +- restarting a virtual machine +- triggering a CI build +- wiping a disk Break down each of the actions into granular operations, then follow the [custom operations][] AEP on how to design them.