Harmonise user experience with Files and closely related objects (like Jobs)

[christophfriedrich]

Discussing issue #126 with @m-mohr revealed that we have to think about files vs. similar objects (like jobs etc.) in general.

We agreed that:

1. Files, jobs, services, and process graphs are essentially the same thing: Entities that exist on the server and are represented by a handler class on the client side. Therefore, they should provide essentially the same functionality and behave essentially the same.
2. The only difference is that the "ID" of a file (i.e. its path+name) is chosen by the user, while the other objects' IDs are random strings generated by the back-end.
3. Technically there's another difference: Files are PUT on the server and are updated with PUT as well. All the others are initially POSTed and then PATCHed if necessary. But this is something users of the client libraries shouldn't care about.
4. Users shouldn't create the handler classes directly (like new Job(...) etc). They either get the handlers via a list function or when returned from a create function.
5. Extending the possibilities given in 4., for some languages/use cases it is necessary (and for others certainly handy) to get a handler not only via a list but also just from the ID (for files: path+name)
6. Every method call to the client API should trigger something on the back-end side.

Therefore I propose the following changes to the client development guidelines:

1. The methods available in Connection scope (create*, list*) should be the same for all of the four types. (There may be additional type-specific methods like validate and execute for process graphs which don't make sense for the other types.)
2. All four type scopes (i.e. File/Job/Service/ProcessGraph) should provide a describe*, update* and delete* method. I.e. the status quo remains except that uploadFile is renamed to updateFile for consistency. The only exception is describeFile which would sound odd and therefore retains its name downloadFile or is changed to retrieveFile (I prefer the latter to avoid that users expecting an upload method when there's a download one).
3. To fulfil no. 5 from above, in Connection scope each type receives an additional get*ById method. To reflect no. 2 from above, for files this may be getFileByName instead of ById, I'm neutral on this.
4. createFile receives another parameter source and immediately uploads the file to the server (to fulfil no. 6 from above). The current behaviour ("getting a File object to work on without uploading anything") can be achieved with the new getFileByName/Id method.

[christophfriedrich]

Edit: If we decide against getFileById it shouldn't be getFileByName but instead getFileByPath to be consistent with #133.

[m-mohr]

I partially incorporated suggestions from here into the client guidelines. Is this better? @christophfriedrich
A big issue with harmonizing the experience is that there is no endpoint to get metadata for a single file so I chose to not use getBy for files. The get*ById calls are now basically shortcuts for var o = new *(); o.describe*();, which is more convenient than having to call describe separately.

[m-mohr]

Closed until further feedback.