addressing comments.

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.