Refactor API

[whitlockjc]

Much like the "make API more RESTful" part of 30x/enrober#25, we need to do the same here.

[tnine]

Agreed. Is this simply a path change, or is it more involved? I ask because we've iterated on this 4 times already. I'm game to give it a review, just don't want to flog a dead horse.

[mpnally]

We should brainstorm. I believe that something like the following would be compatible with the spirit of Josh's new API:

• https://shipyard.e2e.apigee.net/beeswax/images/api/v1/builds/ becomes
  https://shipyard.e2e.apigee.net/builds/
• https://shipyard.e2e.apigee.net/images/namespaces/${APIGEE_ORG}/applications/test-echo/images/1 becomes https://shipyard.e2e.apigee.net/images/${APIGEE_ORG}/test-echo:1
• https://shipyard.e2e.apigee.net/beeswax/images/api/v1/generatepodspec?imageURI=414481387506.dkr.ecr.us-east-1.amazonaws.com/${APIGEE_ORG}/test-echo:1&publicPath=3000:/${APIGEE_ORG}/${APIGEE_ENVIRONMENT_NAME}/test-echo becomes https://shipyard.e2e.apigee.net/defaultpodspec?imageURI=/images/${APIGEE_ORG}/test-echo:1

[tnine]

I'm all for these changes since we have our own virtual host to limit scope to the shipyard services. However, how are we going to handle versioning? This is something we recommend doing to our customers. A simple v1 path segment makes this a very simple versioning scheme. Headers can be done as well, but I feel we need some sort of versioning.

[mpnally]

Versioning is a longer conversation. I believe that putting '/v1' in URLs is useless, and actually harmful. Here is a document I wrote but have never published with some thoughts on versioning. The section on versioning starts on page 44.

With hindsight, I prefer https://shipyard.e2e.apigee.net/defaultpodspec?imageURI=/images/${APIGEE_ORG},test-echo:1 (comma rather than slash)

[tnine]

I'm not sure I agree with the /v1, I agree it can be done with headers. I find a URL path segments easy to digest as a human reading a spec. However, opinions aside, we need to have a stance on this that's consistent across our organization. See this documentation here.

http://apigee.com/about/blog/technology/restful-api-design-tips-versioning

This is what we preach to our customers, are we going to do something different ourselves? If so, we should probably have a good reason.

[mpnally]

Did you get a chance to read the document I linked to? I know we have given different advice in past, but I don't think it was very good advice. I wrote about 10 pages of text explaining why I think that advice wasn't very good. The summary is:

• For the initial introduction, don't do anything for versioning
• There probably never will be a V2, but if there is, you can add something then. There will be no penalty for not having done it for the initial version

[tnine]

I agree with both of your points, not saying I don't. I'm merely pointing out we're introducing some inconsistency between what we're actually going to build and what we tell our customers to build. If this is going to be our standard, we need to ensure we're consistent across all our modules in 30x.