Use consistent naming for endpoints
Today I've had to checkout what endpoints Gitaly provides, and what these have in their response. This was confusing however, as the naming doesn't follow a convention. Or at least its hard to detect what this convention.
For example a piece from the ref proto definition:
service RefService {
rpc FindDefaultBranchName(FindDefaultBranchNameRequest) returns (FindDefaultBranchNameResponse) {}
rpc FindAllBranchNames(FindAllBranchNamesRequest) returns (stream FindAllBranchNamesResponse) {}
rpc FindAllTagNames(FindAllTagNamesRequest) returns (stream FindAllTagNamesResponse) {}
// Find a Ref matching the given constraints. Response may be empty.
rpc FindRefName(FindRefNameRequest) returns (FindRefNameResponse) {}
// Return a stream so we can divide the response in chunks of branches
rpc FindLocalBranches(FindLocalBranchesRequest) returns (stream FindLocalBranchesResponse) {}
rpc FindAllBranches(FindAllBranchesRequest) returns (stream FindAllBranchesResponse) {}
rpc FindAllTags(FindAllTagsRequest) returns (stream FindAllTagsResponse) {}
rpc RefExists(RefExistsRequest) returns (RefExistsResponse) {}
rpc CreateBranch(CreateBranchRequest) returns (CreateBranchResponse) {}
rpc DeleteBranch(DeleteBranchRequest) returns (DeleteBranchResponse) {}
rpc FindBranch(FindBranchRequest) returns (FindBranchResponse) {}
}
Than the NamespaceService:
service NamespaceService {
rpc AddNamespace(AddNamespaceRequest) returns (AddNamespaceResponse) {}
rpc RemoveNamespace(RemoveNamespaceRequest) returns (RemoveNamespaceResponse) {}
rpc RenameNamespace(RenameNamespaceRequest) returns (RenameNamespaceResponse) {}
rpc NamespaceExists(NamespaceExistsRequest) returns (NamespaceExistsResponse) {}
}
As you can see, its really inconsistent. For example, RemoveNamespace
vs DeleteBranch
. But there are quite a lot more. But also for Create
vs Add
.
Proposal for standard verbs:
verb | action | object is singular |
---|---|---|
CreateX | One of X is created, or added. Either way, it reads VerbObject | X |
UpdateX | One of X is updated, in one shape or another. This could be renaming/moving or overriding a property | X |
DeleteX | One of X is removed or deleted. This is always a destructible action and an idempotent action. | X |
FindX | Finds one item by a certain default id. In the case of a commit this would be the SHA1. | X |
FindXByY | Finds one item by uniquely identifiable Y. A valid listing of X in the response X is singular | X |
ListXs | List all of X, if needed might take filtering params. E.g. ListTags | |
ListXsByY | List all of X, that have a certain property Y. If needed it might take filtering params. E.g. ListTagsByAuthor | |
IsPropertyX | Checks a certain property, for example IsEmptyRepository or IsSignedCommit . Returns a boolean, or throws an error |
X |
Now, going back to the previously listed RefService, one might ask how this will work when filtering on a ref being a Tag or Branch for example. This could go in one of two ways:
- The ListRef endpoint might take a filter Tag=true
- Split it to a BranchService with a ListBranch action and a TagService with a ListTags.
On the last listed item in the table, IsExistsRepository
doesn't read right, but in this case FindRepository
should be used, and the result is either nil or a valid object, signalling if it exists or not.