API Design Tour: Dell

Editor's Notes

1. Creative Commons Attribution-Share Alike 3.0 United States License
2. Dell Inc. provides integrated technology solutions in the information technology (IT) industry worldwide
3. Opportunity: Monetize Dell services, solutions, capabilities through API Tool for Dell to open our portfolio of solutions to our customersBuild on success and expand API services to generate revenueEnable high ROI programsStarted as an innovation center incubation project to explore the best possible options to connect partners and customers with valuable Dell internal services.
4. Our target developers are mainly internal and partners. Eventually we want to open our API’s to external “man on the street” developers. But currently we find a lot of opportunity with exposing it to our partners and internal developers through “Dell Hackathons”
5. Talking points: Support services API’s - Order status, case management, Support historyMobile API’sCommunity API’sCompany acquisition -> taking orders internationally and calculating taxes. Integrate order processing capabilities. Exposed tax calc as an API.
6. We follow the “pragmatic REST” philosophy .Currently most of our internal services are all SOAP based and we sometimes do spend cycles RESTifying them and externalize.There is a push to ensure that internal services are designed with REST principles so they can be exposed externally with minimal effort, unlocking their value faster.
7. The ones that have generated the most discussion are those around defining service levels and throttling limits. We have found that it is an ever changing definition, getting refined with over time with new API and associated clients. We need to adapt the service levels to the needs of our clients and the constraints of our internal services, which has been a challenging, but a nice intellectual exercise.The other is around versioning and how do we manage communication around internal service version changes and how it affects clients usign our API’s
8. Handles as part of query string parameters in the header
9. If metadata is requested, we can return it as part of the response header or modify the response body as needed by the client.
10. Counting is normally not supported unless it is supported by the internal service of the relevant API. Currently we have it only for one of our support services.
11. Currently as many other folks, we mainly use GET, as the request is to provide information from our services, like Order Status. We also use POST for some of our API methods where it is necessary to provide update or create new information. For e.g., community posting, or creating a new issue ticket.In some instances, we use POST slightly differently due inherent limitations with GET for our needs. We use POST in some cases to do a GET or Search.
12. Typically we try to adopt the standard POX convention without namespaces for most as its easier for our users. The data contract though, will likely be different for every API.
13. Version information is part of the URI. Its mandatory we manage versions appropriately since our internal services could drastically change with releases. We provide support for two versions at a time, with appropriate deprecation policy defined and communicated. Most of our versions are long lived, and it can take up to a year or more to deprecate an earlier version.
14. We endeavor to keep our URI intact for changes. All our changes get absorbed within the application, so the user does not see any changes that they need to adapt to. If there is a major change like a platform upgrade (which is rare), we do plan to deprecate the older versions. We try to give users appropriate notice and keep our communication channels open till the process is complete.
15. Currently we do not handle search in any of our API’s.
16. NOTES:Developer portal is currently internalAssetinfo is an example of a support services API
17. Currently all our authentication is handled through API Keys. We are starting to use Dell account authentication for some of our clients. We are planning to offer OAUTH authentication as soon as the internal service teams start supporting it in production (currently in testing).
18. We do not have an SDK out there currently. We do provide code samples including request/response parameters for all our API’s
19. We ensure that performance is maximized by keeping the functionality at the API layer to a minimum, if it can all be handled by the underlying service. For example that was the case in one of our recent implementations and we just let the data pass through the API layer with minimal/no impact performance impacts in servicing the requests. In some instances we might have to do some processing on the data fetched from the internal services, in these instances we endeavor to separate the data fetch operation from the user request one so we can keep performance impacts to the minimum. The trade-off is slightly stale data.
20. Internal service readiness. Working closely with internal service teams to ensure they are on boardManaging limits on service Vs. client expectations of the service. Defining appropriate service levels and planning for growth, particularly on the infrastructure sideHaving an appropriate support and communication strategy in place before releasing the API’s in to the wild.Defining process for service level upgrade and associated costs.Don’t forget marketing your API’s and the good work within the company to get people thinking of how they can leverage what has been created or add to the mix.