Design of application programming interfaces (APIs)

• US 7,430,732 B2
• Filed: 10/23/2003
• Issued: 09/30/2008
• Est. Priority Date: 10/23/2003
• Status: Expired due to Fees

• Current Assignee: Microsoft Technology Licensing LLC (Microsoft Corporation)
• Original Assignee: Microsoft Corporation
• Inventors: Moore, Anthony J., Anderson, Christopher L., Cwalina, Krzysztof J., Brigham, Robert Allan II, Pizzo, Michael, Abrams, Bradley Moore
• Primary Examiner(s): Zhen; Wei Y.
• Assistant Examiner(s): Chen; Qing
• Application Number:
  US10/692,320
• Publication Number:
  US 20050091660A1
• Time in Patent Office: 1,804 Days
• Field of Search: 717106-113, 717124-135, 719328-329
• US Class Current: 717/126
• CPC Class Codes: G06F 8/20 Software design

Abstract

A first exemplary method implementation for designing an application programming interface (API) includes: preparing multiple code samples for a core scenario, each respective code sample of the multiple code samples corresponding to a respective programming language of multiple programming languages; and deriving the API from the core scenario responsive to the multiple code samples. A second exemplary method for designing an API includes: selecting a core scenario for a feature area; writing at least one code sample for the core scenario; and deriving an API for the core scenario responsive to the at least one code sample. A third exemplary method for designing an API includes: deriving an API for a scenario responsive to at least one code sample written with regard to the scenario; performing one or more usability studies on the API utilizing multiple developers; and revising the API based on the one or more usability studies.

Claims

1. A method for designing an Application Programming Interface (API), the method comprising:

preparing a plurality of code samples for a core scenario, each respective code sample of the plurality of code samples corresponding to a respective programming language of a plurality of programming languages;

deriving the API from the core scenario responsive to the plurality of code samples, wherein the deriving comprises producing a two-layer framework that includes component types targeting a relatively higher level of abstraction and component types targeting a relatively lower level of abstraction, wherein the relatively lower level of abstraction is lower in abstraction than the relatively higher level of abstraction;

wherein the component types targeting the relatively higher level of abstraction are directed to core scenarios; and

wherein the component types targeting the relatively lower level of abstraction provide a relatively greater amount of control to developers as compared to the component types targeting the relatively higher level of abstraction, which provide a relatively lower amount of control to the component types, wherein the relatively lower amount of control is a lower amount of control than the relatively greater amount of control;

performing one or more usability studies on the API utilizing a plurality of developers, wherein the one or more usability studies comprise;

determining, by an API designer, whether the plurality of developers are able to use the API without problems; and

when the plurality of developers are determined not to be able to use the API without problems, then revising, by the API designer, the API based on the one or more usability studies to produce a revised API; and

realizing the API in one or more processor-accessible storage media.

2. The method as recited in claim 1, further comprising:

determining, by the API designer, if the API is more complex than desired.

3. The method as recited in claim 2, further comprising:

if the API is determined to be more complex than desired, then

refining, by the API designer, the API to produce a refined API.

4. The method as recited in claim 3, further comprising:

determining, by the API designer, if the refined API is more complex than desired.

5. The method as recited in claim 1, wherein the performing comprises:

performing the one or more usability studies on the API utilizing the plurality of developers wherein the plurality of developers are competent with the plurality of programming languages.

6. The method as recited in claim 1, wherein the deriving comprises:

deriving the API to support the plurality of code samples that correspond respectively to the plurality of programming languages.

7. The method as recited in claim 1, wherein the deriving comprises:

gleaning language-specific mandates from the plurality of code samples; and

incorporating the language-specific mandates into the API.

8. The method as recited in claim 1, wherein the deriving comprises:

gleaning language-inspired developer expectations from the plurality of code samples; and

incorporating the language-inspired developer expectations into the API.

9. The method as recited in claim 1, wherein the deriving comprises:

gleaning commonalities from the plurality of code samples; and

incorporating the commonalities into the API.

10. The method as recited in claim 1, wherein the deriving comprises:

deriving the API to have an aggregate component that ties a plurality of lower-level factored types together to support the core scenario.

11. A method for designing an Application Programming Interface (API), the method comprising:

selecting a core scenario for a feature area;

writing at least one code sample for the core scenario;

deriving an API for the core scenario responsive to the at least one code sample, wherein the deriving comprises producing a two-layer framework that includes component types targeting a relatively higher level of abstraction and component types targeting a relatively lower level of abstraction, wherein the relatively lower level of abstraction is lower in abstraction than the relatively higher level of abstraction;

wherein the component types targeting the relatively higher level of abstraction are directed to core scenarios; and

wherein the component types targeting the relatively lower level of abstraction provide a relatively greater amount of control to developers as compared to the component types targeting the relatively higher level of abstraction, which provide a relatively lower amount of control to the component types, wherein the relatively lower amount of control is a lower amount of control than the relatively greater amount of control;

performing one or more usability studies on the API utilizing a plurality of developers, wherein the one or more usability studies comprise;

determining, by an API designer, whether the plurality of developers are able to use the API without problems; and

when the plurality of developers are determined not to be able to use the API without problems, then revising, by the API designer, the API based on the one or more usability studies to produce a revised API; and

realizing the API in one or more processor-accessible storage media.

12. The method as recited in claim 11, wherein the selecting comprises:

selecting a plurality of core scenarios for the feature area.

13. The method as recited in claim 12, further comprising:

repeating the writing and the deriving for each core scenario of the plurality of core scenarios that are selected for the feature area.

14. The method as recited in claim 11, wherein the writing comprises:

writing a plurality of code samples for the core scenario, each respective code sample of the plurality of code samples corresponding to a respective programming language of a plurality of programming languages.

15. The method as recited in claim 14, wherein the deriving comprises:

deriving the API for the core scenario responsive to the plurality of code samples.

16. The method as recited in claim 11, further comprising:

repeating the performing and the determining with respect to the revised API.

17. The method as recited in claim 11, wherein the deriving comprises:

deriving the API to support the at least one code sample written for the core scenario by producing a two-layer API that includes an aggregate component and a plurality of underlying factored types.

18. The method as recited in claim 11, wherein the deriving comprises:

gleaning one or more language-specific mandates from the at least one code sample; and

incorporating the one or more language-specific mandates into the API.

19. The method as recited in claim 11, wherein the deriving comprises:

encapsulating a particular factored type into an aggregate component that is associated with the core scenario if all members of the particular factored type are exposed by the aggregate component.

20. The method as recited in claim 11, wherein the deriving comprises:

encapsulating a particular factored type into an aggregate component that is associated with the core scenario if the particular factored type is independently unrelated to other component types.

21. The method as recited in claim 11, wherein the deriving comprises:

exposing a particular factored type from an aggregate component that is associated with the core scenario if at least one member of the particular factored type is not exposed by the aggregate component.

22. The method as recited in claim 11, wherein the deriving comprises:

exposing a particular factored type from an aggregate component that is associated with the core scenario if the particular factored type can be beneficially used independently of the aggregate component by another component type.

23. The method as recited in claim 11, wherein the deriving comprises:

deriving the API so as to enable a developer to implement a create-set-call usage pattern for the core scenario.

24. The method as recited in claim 23, wherein the deriving comprises:

producing the API with pre-selected parameters that are appropriate for the core scenario.

25. A method for designing an Application Programming Interface (API), the method comprising:

deriving an API for a scenario responsive to at least one code sample written with regard to the scenario, wherein the deriving comprises producing a two-layer framework that includes component types targeting a relatively higher level of abstraction and component types targeting a relatively lower level of abstraction, wherein the relatively lower level of abstraction is lower in abstraction than the relatively higher level of abstraction;

wherein the component types targeting the relatively higher level of abstraction are directed to core scenarios; and

wherein the component types targeting the relatively lower level of abstraction provide a relatively greater amount of control to developers as compared to the component types targeting the relatively higher level of abstraction, which provide a relatively lower amount of control to the component types, wherein the relatively lower amount of control is a lower amount of control than the relatively greater amount of control;

performing one or more usability studies on the API utilizing a plurality of developers, wherein the one or more usability studies comprise;

determining, by an API designer, whether the plurality of developers are able to use the API without problems; and

when the plurality of developers are determined not to be able to use the API without problems, then revising, by the API designer, the API based on the one or more usability studies to produce a revised API; and

realizing the API in one or more processor-accessible storage media.

26. The method as recited in claim 25, further comprising:

writing a plurality of code samples with regard to the scenario, each respective code sample of the plurality of code samples corresponding to a respective programming language of a plurality of programming languages;

wherein the deriving comprises;

deriving the API for the scenario responsive to the plurality of code samples.

27. The method as recited in claim 25, further comprising, prior to the performing one or more usability studies on the API:

determining, by the API designer, if the API is more complex than desired;

if the API is determined to be more complex than desired, then

refining, by the API designer, the API to produce a refined API; and

determining, by the API designer, if the refined API is more complex than desired.

28. The method as recited in claim 25, further comprising:

repeating at least the performing and the determining with respect to the revised API.

29. The method as recited in claim 25, wherein the determining comprises:

determining whether the plurality of developers are able to use the API without problems with regard to a desired level of usability for at least one targeted developer group, wherein the desired level of usability includes considerations with respect to (i) frequent and/or extensive reference to detailed API documentation by the plurality of developers, (ii) a failure of a majority of the plurality of developers to implement the scenario, and (iii) whether the plurality of developers take an approach that is different from what is expected by the API designer.

30. The method as recited in claim 25, further comprising:

selecting a plurality of core scenarios for a feature area; and

repeating the deriving, the performing, and the revising for each core scenario of the plurality of core scenarios.

31. The method as recited in claim 30, wherein the deriving comprises:

producing an aggregate component for each core scenario of the plurality of core scenarios.

32. The method as recited in claim 25, wherein the deriving comprises:

producing an aggregate component that has a respective relationship with each respective factored type of a plurality of factored types.

33. The method as recited in claim 32, wherein the producing comprises:

producing the aggregate component to support the scenario for which the at least one code sample is written.

34. The method as recited in claim 32, wherein the producing comprises:

producing the aggregate component to have an exposed relationship with at least one factored type of the plurality of factored types and an encapsulated relationship with at least one other factored type of the plurality of factored types.

35. The method as recited in claim 34, wherein the at least one other factored type of the plurality of factored types that has the encapsulated relationship with the aggregate component can be handed off by the aggregate component for direct interaction with another component type.

36. The method as recited in claim 32, wherein the plurality of factored types are designed using an object-oriented methodology.

37. A method for designing an Application Programming Interface (API), the method comprising:

preparing a plurality of code samples for a core scenario, each respective code sample of the plurality of code samples corresponding to a respective programming language of a plurality of programming languages;

deriving the API for the core scenario responsive to the plurality of code samples, wherein the deriving comprises producing a two-layer framework that includes component types targeting a relatively higher level of abstraction and component types targeting a relatively lower level of abstraction, wherein the relatively lower level of abstraction is lower in abstraction than the relatively higher level of abstraction;

wherein the component types targeting the relatively higher level of abstraction are directed to core scenarios; and

wherein the component types targeting the relatively lower level of abstraction provide a relatively greater amount of control to developers as compared to the component types targeting the relatively higher level of abstraction, which provide a relatively lower amount of control to the component types, wherein the relatively lower amount of control is a lower amount of control than the relatively greater amount of control;

performing one or more usability studies on the API utilizing a plurality of developers, wherein the one or more usability studies comprise;

determining, by an API designer, whether the plurality of developers are able to use the API without problems; and

when the plurality of developers are determined not to be able to use the API without problems, then revising, by the API designer, the API based on the one or more usability studies to produce a revised API; and

realizing the API in one or more processor-accessible storage media.

38. A method for designing an Application Programming Interface (API), the method comprising:

writing at least one code sample for a scenario;

deriving an API for the scenario responsive to the at least one code sample, the API including (i) an aggregate component that is adapted to facilitate implementation of the scenario and (ii) a plurality of factored types that provide underlying functionality for the aggregate component, the API enabling a progression from using the aggregate component in simpler situations to using an increasing portion of the plurality of factored types in increasingly complex situations, wherein the simpler situations are less complex than the increasingly complex situations;

wherein the deriving comprises producing a two-layer framework that includes component types targeting a relatively higher level of abstraction and component types targeting a relatively lower level of abstraction, wherein the relatively lower level of abstraction is lower in abstraction than the relatively higher level of abstraction;

wherein the component types targeting the relatively higher level of abstraction are directed to core scenarios; and

wherein the component types targeting the relatively lower level of abstraction provide a relatively greater amount of control to developers as compared to the component types targeting the relatively higher level of abstraction, which provide a relatively lower amount of control to the component types, wherein the relatively lower amount of control is a lower amount of control than the relatively greater amount of control;

performing one or more usability studies on the API utilizing a plurality of developers, wherein the one or more usability studies comprise;

determining, by an API designer, whether the plurality of developers are able to use the API without problems; and

when the plurality of developers are determined not to be able to use the API without problems, then revising, by the API designer, the API based on the one or more usability studies to produce a revised API; and

realizing the API in one or more processor-accessible storage media.

39. A method for designing an Application Programming Interface (API), the method comprising:

deriving at least one aggregate component to support at least one code sample for at least one scenario, wherein the deriving comprises producing a two-layer framework that includes component types targeting a relatively higher level of abstraction and component types targeting a relatively lower level of abstraction, wherein the relatively lower level of abstraction is lower in abstraction than the relatively higher level of abstraction;

wherein the component types targeting the relatively higher level of abstraction are directed to core scenarios; and

wherein the component types targeting the relatively lower level of abstraction provide a relatively greater amount of control to developers as compared to the component types targeting the relatively higher level of abstraction, which provide a relatively lower amount of control to the component types, wherein the relatively lower amount of control is a lower amount of control than the relatively greater amount of control;

determining additional requirements with respect to the at least one scenario;

deciding if the additional requirements can be added to the at least one aggregate component without adding more complexity than desired to the at least one scenario;

if it is decided that the additional requirements can not be added to the at least one aggregate component without adding more complexity than desired to the at least one scenario, then;

defining a plurality of factored types responsive to the deciding;

performing one or more usability studies on the at least one aggregate component utilizing a plurality of developers, wherein the one or more usability studies comprise;

determining, by an API designer, whether the plurality of developers are able to use the at least one aggregate component without problems; and

when the plurality of developers are determined not to be able to use the at least one aggregate component without problems, then revising, by the API designer, the at least one aggregate component based on the one or more usability studies to produce a revised aggregate component; and

realizing the at least one aggregate component in one or more processor-accessible storage media; and

realizing the plurality of factored types in the one or more processor-accessible storage media; and

if it is decided that the additional requirements can be added to the at least one aggregate component without adding more complexity than desired to the at least one scenario, then;

refining the at least one aggregate component to incorporate the additional requirements;

performing one or more usability studies on the refined at least one aggregate component utilizing a plurality of developers, wherein the one or more usability studies comprise;

determining, by an API designer, whether the plurality of developers are able to use the refined at least one aggregate component without problems; and

when the plurality of developers are determined not to be able to use the refined at least one aggregate component without problems, then revising, by the API designer, the refined at least one aggregate component based on the one or more usability studies to produce a revised aggregate component; and

realizing the refined at least one aggregate component in the one or more processor-accessible storage media.

40. The method as recited in claim 39, further comprising:

selecting a plurality of core scenarios for a feature area, the plurality of core scenarios including the at least one scenario; and

writing a plurality of code samples showing preferred lines of code for the plurality of core scenarios, the plurality of code samples including the at least one code sample;

wherein the deriving comprises;

deriving a plurality of aggregate components, which include the at least one aggregate component, to support the plurality of code samples for the plurality of core scenarios.

41. The method as recited in claim 39, wherein the deriving comprises:

deriving the at least one aggregate component with methods, defaults, and abstractions to support the at least one code sample for the at least one scenario.

42. The method as recited in claim 39, further comprising:

refining the at least one code sample according to the at least one derived aggregate component;

evaluating the refined at least one code sample with regard to simplicity; and

repeating the deriving if the refined at least one code sample fails to be as simple as desired as determined in the evaluating.

43. The method as recited in claim 39, wherein the determining comprises:

determining additional requirements with respect to the at least one scenario, wherein the additional requirements include additional scenarios, additional usages, and additional interactions with other component types.

44. The method as recited in claim 39, wherein the deciding comprises:

considering whether adding the additional requirements to the at least one aggregate component hinders a create-set-call usage pattern.

45. The method as recited in claim 39, wherein the defining comprises:

defining the plurality of factored types responsive to the deciding with a factoring of a full set of functionality.

46. The method as recited in claim 39, wherein the defining comprises:

defining the plurality of factored types responsive to the deciding using one or more object-oriented methodologies.

47. The method as recited in claim 39, further comprising:

determining whether the at least one aggregate component is to encapsulate or expose the functionality of each factored type of the plurality of factored types.

48. The method as recited in claim 39, further comprising:

refining the plurality of factored types to support the at least one aggregate component and the additional requirements.