Hmm, after thinking more about this, I realized that will need to expand the API to cover the commit negotiation that @sinbad described in his original pull-request. I added partial support for this in 6864ac5, but I will have to think about a more flexible flow to support more implementations.

Demoting this PR to a [WIP] as I still have to consider some final thoughts for the lock-listing API. In particular:

Pagination is a bit of a tricky subject, since there is no guarantee that a client will get all of the locks they requested if a multipage response is returned and a new lock was created while paginating through the n-th page of that response. @technoweenie and I discussed that perhaps the best way around this was to eliminate the notion of "pages" and instead make it a requirement that the server return results in a reverse-chronological ordering. Clients could instead send the last UUID that they received and the server would send them n results after that, and we'd still keep the HasMore bool.

The other thing I have yet to decide upon is the filtering mechanism. The current filter definition that I proposed:

type Filter struct {                                               
        // Prop is the property to search against.         
        Prop Property `json:"prop"`                        
        // Value is the value that the property must take. 
        Value string `json:"value"`                        
}

works well for equality operations, but fails for <, >, and != operations. This is sort of a rabbit-hole, since once you consider adding operations for < and >, it's easy to add nested filters and ANDs, ORs, and XORs. I'm not sure how far we should take this idea, but if we pursue the idea of nested filters, I could work on an API to accommodate that.

I like the type definitions, but I think it'd be helpful thinking about the API too. For example, I'm not sure unlocking will require a struct like this:

// An UnlockRequest is sent by the client over the API when they wish to remove
// a lock associated with the given UUID.
type UnlockRequest struct {
        // UUID is the identifier of the lock that the client wishes to remove.
        UUID string `json:"path"`
}

Given an LFS base url of https://git-server.com/repo/info/lfs, the unlock API call could be something like POST https://git-server.com/repo/info/lfs/locks/{uuid} -d {"operation":"unlock", ...}.

Also, I think the spec should recommend that server implementations keep locks for auditing purposes. This is why the unlock action is a POST to the resource, and not a DELETE.

On second thought, the currently proposed filter API might be alright for V1. I'm not sure the >/< operators are that useful for anything other than created_at time. It would be nice to greater support for nested filters, but I move that we adopt the current model for now, and expand on it in v2 if we find a greater need for more filtering operations.

Merging this. Great job finishing the proposal, time to get crackin on a prototype 🤘

Thanks, @technoweenie! Let's do it.