Hi Chris,

Comments inline with what we have today.

On 7/18/13 12:57 PM, "Chris Wright" <chrisw@...> wrote:

After the recent round of project proposal reviews I'm wondering about
APIs and whether we need to include any API review at some stage in the
lifecycle or release process.

Things that I think are important are:

1) Identifying the APIs. This is largely just documenting what is there
to help developers.

We use Enunciate plugin on all the northbound bundles to auto-generate the
REST Northbound APIs.
The following link consolidates the auto-generated REST-API documentation :

https://wiki.opendaylight.org/view/OpenDaylight_Controller:REST_Reference_a
nd_Authentication

Similar to JavaDoc, we must continue to use such plugins to auto-generate
the Northbound APIs
for every gerrit push & merge.

2) Making APIs consistent. Following some fairly predictable patterns.
CRUD helps, but more eyes on what resources and attributes are exposed is
probably a good thing.

Yes. The currently available APIs use Jersey and JAXB frameworks to bring
in consistency in the
Way the REST APIs are defined. But the API definition itself is something
needs proper review by
the community. Northbound Integration Test is another place to enforce
some consistencies.

3) Making APIs that are not overlapping. Ensuring that we have unique
ways to access controller resources could require some cross-project
coordination or review.

Agreed. Cross-project coordination and review is key in making it
consistent.
If we begin with using the common tools (enunciate, Jersey, JAXB,
NB-Integration-Test), it will
Form as the first level of defense.
There is also discussions in MD-SAL to automate the API generation using
Yang tools used in
Conduction with the SB Plugins.

-Madhu

I'm looking for feedback on whether folks agree that reviewing the APIs
is something that the TSC should take one? And then, if so, specifically
where in the process?

thanks,
-chris
_______________________________________________
TSC mailing list
TSC@...
https://lists.opendaylight.org/mailman/listinfo/tsc

All good ideas. This has been informally discussed amongst some of us.
For example, how does the SAL provide a common layer of abstraction but
then the user be able to explicitly access the non-commonly-abstractable
functionality of an underlying SB ...the same can be said of any service.
The extensible model concept proposed by the SAL should address large
swaths of this, but I don't think EVERYTHING falls under tha umbrella
...so, ...yeah ...all that.

After the recent round of project proposal reviews I'm wondering about
APIs and whether we need to include any API review at some stage in the
lifecycle or release process.

Things that I think are important are:

1) Identifying the APIs. This is largely just documenting what is there
to help developers.

2) Making APIs consistent. Following some fairly predictable patterns.
CRUD helps, but more eyes on what resources and attributes are exposed is
probably a good thing.

3) Making APIs that are not overlapping. Ensuring that we have unique
ways to access controller resources could require some cross-project
coordination or review.

I'm looking for feedback on whether folks agree that reviewing the APIs
is something that the TSC should take one? And then, if so, specifically
where in the process?

thanks,
-chris