It might be better to use a URI template here: `/notifications{?all,participating,since}

Ah dang, I should make all the urls into templates. Thanks for reminding me.

Also, do you prefer parameters or endpoints like/notifications/all and/notifications/participating? I guess they are technically separate collections.

Does this mark all notifications a read? If not now is the appropriate notification identified? Wouldn'tDELETE be more appropriate than POST?

Yes, this endpoint is for all notifications. There's also a per-repository URL: "/repos/:owner/:name/mark". Summaries have their own endpoint,/notifications/summaries/:id/mark.

I used POST instead of DELETE because you can still see the notifications if you pass?all=1.

I see.DELETE might be a little weird in that case. I don't really like those rpc style actions, though. I prefer the following

==>

PUT /notifications/summaries/:idcontent-type: app/v3{unread: false}

<===

200 OK

The double negative of the unread property in this case is a little awkward. Maybe this would be a better ux:

===>   PUT /notifications/summaries/:id  content-type: app/v3  {read: true}<----  200 OK

Would this be applicable for collections too?

PUT /notifications{read: true}

I thinkPUT would be a better method for this. Even if we don't want clients to have to send the full representation we should still usePUT. A PUT w/o a complete long form representation is not a "partial put" unless the server is unable to take that representation and convert it into the full representation using the existing state of the system in an idempotent manner. So PUTs with a range header are partial and not ok because if you repeat them they are not idempotent. PUTs with a "lite" representation of the resource arenot partial puts, even though that "lite" representation does not include all the resource information.

Well, we use PATCH everywhere else. Had a big discussion internally and on Twitter back when I was designing the API. Seems like a difference in the vague specs are interpreted.

At least for now, I think going with PATCH for consistency is best.

probably, i just hate patch so much fo this type of use case.