How do we remove or change obsolete methods? One idea may be to follow the java model and mark the API in some way as 'deprecated'. Mrogers 13:20, 29 December 2008 (UTC) lifecycle attribute implemented. We now have a 'deprecated' state.
Java script API
Do we need to worry about the Java Script API? There's lots of implementations (such as Activities feed) that are in Java only. Should we be saying use java only for those cases such as streaming interfaces that can't be handled by Java Script. Script API design guidelines
We are going to use the dictionary service as a guinea pig for the processing of deep collections.
Parent / child objacts may have
level 1, summary : summary details of parent + references of children
level 2, normal : full parent + summary of children
level 3, kitchen sink : full parent + full details of all children.
Check in / check out pattern for large graphs of objects
The approach for inbound integrations is loosely based on the â€œcheck out / check inâ€ paradigm, where the system requesting a change is first required to â€œcheck outâ€ the object it wishes to modify from the target system, modify it as needed and finally â€œcheck inâ€ the modified object to the target system. The primary advantages of this model are:
the object that is checked out can be as structurally complex as required, thereby:
Covering a wide variety of use cases through a minimal set of operations
improving performance by minimizing the number of round trips in order to retrieve an entire object (including sub-objects)
merging the updated object with Alfresco's version of the object is simplified, since both versions of the object are available at the same time
transformation is simplified because merging occurs from the originating systemâ€™s representation of the object directly to Alfresco's representation of the object
validation is simplified since it can be performed by the client prior to attempting to check the changes into Alfresco
the window of opportunity for concurrent modifications is minimized due to Alfresco retrieving the latest copy of the data immediately prior to modifying and saving it
development is simplified, due to the small, fixed number of operations that are required, and because the resulting system adheres to the command / query separation principle
10:19, 6 November 2008 (UTC) idea for discussion
Empty result sets
Suppose we do a search that finds no data. How do we represent this? null, empty array or exception?
How to format description
Here is an example of a formatted description from the CMIS API. It shows how to format the description field.
I'm putting this forward as a good example to copy.
String url: CMIS service url of the repository to test
String user: username/password for authentication (HTTP BASIC Authentication)
String args: Enum url, headers or both - dictates how arguments are passed to services (Default: url)
boolean validate: true => validate repository responses against CMIS XSDs
boolean trace: true => trace request and response bodies String tests: names of tests to execute (use * in test name to represent wildcard) (Default: *)
And here is an example for a JSON method.
If the optional webApp argument is specified then reverts the modified assets within that web app.
JSON data fileds
boolean is this submit all? (optional)
array, of JSON objects containing a path property (optional). If the 'all' option is true then this parameter is ignored
array, of String paths (optional). If the 'all' option is true then this parameter is ignored
Mrogers 10:41, 5 December 2008 (UTC) Using JavaDoc/JSDoc as a template As a developer I need to know the description, parameters, arguments, return value and exception data. The above example has 'Inputs'.
to be processed
consider design of resources, how they relate and requests they support rather than think about design of URIs (that's secondary)
document in web script description
grouping together lists of commands for one unit of work