Hello,
we are looking for advice on an API-design question. The question is
related to our proposed extensions for managing Xen security policies
through the Xen-API, but we think that the discussion can be lead on a
more abstract level to get more input from a wider audience.
On a more concret level and as background: The problem is related to the
fact that today there is one type of security policy in Xen, but in the
future there might be different ones. The Xen-API extensions that we are
proposing should be able to accomodate those future extensions as well
thorugh the function calls we are providing, though today we might not
exactly know how these extensions look like, what functions they need and
what paramters those functions need.
For the design of our current API we considered the kind of functionality
we wanted to have and created an API with function signatures having
*well-defined input parameters and output parameters* in forms of data
types and structures. This lead to the design of a *broad API* with very
specilized calls that work well for what we want to do with what we have
today, but these calls are likely not able to work with different types of
policies due to the parameters passed to these functions and the type of
return values they get.
In trying to accomodate future extensions where we would likely not know
the parameters needed for function calls, we could resort to a *narrow
API* with rather generic function call names where we would pass an
operation code about what the function is supposed to do along with some
form of encoding parameters needed for the operation. This encoding of the
parameters might be a 'char *' with a string in XML form. The return value
could also be in form of XML.
[.A scheme definition of the XML, though, would in turn reflect that we
still don't know what the future parameters might be and might therefore
again be subject to change.]
Another option would be to pass a structure that can accomodate our
current well-defined input parameters and adapt the structure when new
parameters are needed in future version of a library.
So what the decision comes down to is the choice of either implementing a
broad API with functions taking well-defined data types and structures
where new functions might need to be add in the future to accomodate
future functionality *OR* a generic API with generic function names and
parameters that might not need to be extended.
Some background knowledge on the implementation-level of such things
inside the libxen 'C' library helps:
It is easy to have well-defined data structures (and arrays of those)
serialized and deserialized by libxen for easy creation and consumption of
datstructures by applications using the Xen-API. This would speak for a
broad API with well-defined data structures. XML-encoded parameters and
results, on the other hand, would require creation and parsing of the
parameters and return values by an application, but could accomodate
future extensions more easily.
Any insights on such a design decision are welcome.
Stefan
we are looking for advice on an API-design question. The question is
related to our proposed extensions for managing Xen security policies
through the Xen-API, but we think that the discussion can be lead on a
more abstract level to get more input from a wider audience.
On a more concret level and as background: The problem is related to the
fact that today there is one type of security policy in Xen, but in the
future there might be different ones. The Xen-API extensions that we are
proposing should be able to accomodate those future extensions as well
thorugh the function calls we are providing, though today we might not
exactly know how these extensions look like, what functions they need and
what paramters those functions need.
For the design of our current API we considered the kind of functionality
we wanted to have and created an API with function signatures having
*well-defined input parameters and output parameters* in forms of data
types and structures. This lead to the design of a *broad API* with very
specilized calls that work well for what we want to do with what we have
today, but these calls are likely not able to work with different types of
policies due to the parameters passed to these functions and the type of
return values they get.
In trying to accomodate future extensions where we would likely not know
the parameters needed for function calls, we could resort to a *narrow
API* with rather generic function call names where we would pass an
operation code about what the function is supposed to do along with some
form of encoding parameters needed for the operation. This encoding of the
parameters might be a 'char *' with a string in XML form. The return value
could also be in form of XML.
[.A scheme definition of the XML, though, would in turn reflect that we
still don't know what the future parameters might be and might therefore
again be subject to change.]
Another option would be to pass a structure that can accomodate our
current well-defined input parameters and adapt the structure when new
parameters are needed in future version of a library.
So what the decision comes down to is the choice of either implementing a
broad API with functions taking well-defined data types and structures
where new functions might need to be add in the future to accomodate
future functionality *OR* a generic API with generic function names and
parameters that might not need to be extended.
Some background knowledge on the implementation-level of such things
inside the libxen 'C' library helps:
It is easy to have well-defined data structures (and arrays of those)
serialized and deserialized by libxen for easy creation and consumption of
datstructures by applications using the Xen-API. This would speak for a
broad API with well-defined data structures. XML-encoded parameters and
results, on the other hand, would require creation and parsing of the
parameters and return values by an application, but could accomodate
future extensions more easily.
Any insights on such a design decision are welcome.
Stefan