Getting Started with the Cloud Solution Provider APIs

Article
08/26/2015

If you're a Cloud Solution Provider (CSP) partner, you have many options for transacting your customers orders with Microsoft. In this post I'll walk through getting started with the CSP Application Programming Interfaces (APIs) and point you to some resources for learning more about them.

Do you need to use APIs for Integration?

Most partners who undertake CSP API integration work do so because they have an existing customer portal where their customers purchase from them and they want to have direct integration between that portal and Microsoft. This would enable the partner to sell Microsoft commercial cloud services directly from their own portal through the CSP program. Here are some other options for selling through the CSP program.

Code against CSP APIs - this is what I'll focus on below in the post
Use Partner Center web site - You can use the Partner Center web site that Microsoft provides, but your customers cannot access that so you have to place the orders for them
Panel Providers Prebuilt Portal - You can use a 'control panel' from an ISV who specializes in that and their software will access the CSP APIs on your behalf
Use a Distributors Portal - If you are a reseller working with a 2 tier CSP distributor then you would normally use the portal that the distributor provides
Hire Third Party Developer - The other way you can avoid coding against the APIs is to hire developers who can do it for you

Pre-requisites

To be successful with the Cloud Solution Provider CREST APIs you should already have the following pre-requisites:

Must be already on-boarded as a Cloud Solution Provider partner with access to https://partnercenter.microsoft.com
Have developers with experience using REST and JSON. All integration with the CSP APIs uses industry standards based REST and JSON message formats over HTTPS.
Ideally developers should also have experience with Azure AD authentication and C#. It is not required to use C# since the APIs are available to any language which supports REST, however we provide the most comprehensive sample code in C# using Visual Studio 2015 and .NET Framework 4.5.

Suggested Developer Training Plan

Make sure you know who your software developers are who will be working on the integration project. Perhaps it is you. That person should review the available training material for working with the CSP APIs. We have links to this at the end of this document and it includes videos, MSDN documentation, MSDN forums FAQs, Code samples, and additional guidance.

Once the introductory material is completed. Developers can get up to speed by working through these exercises:

Request an integration sandbox account from Partner Center
Request an App ID and client secret from Partner Center
Build and run the CSP sample code from GitHub
Build and run an Azure AD sample from GitHub
Run a network trace and monitor the HTTP request and response

Example Integration Project and Development Sizing

Most partners who are integrating with the CSP APIs have an existing customer portal system that they sell to customers with. This customer portal may be linked to other internal systems such as an ordering system and a billing system. These existing systems need to work with an interface module that connects to the CSP APIs as shown in the following diagram.

A project plan for the integration work should include the following steps:

Training time for developers on new tools and technologies
Document system architecture of existing customer portal and associated systems
Plan for CSP API integration points
Review system architecture changes and improve
Build out code proof of concept using CSP Integration Sandbox
Review proof of concept code and improve
Build solution

To determine how much work will be required for this integration we recommend you have the team that would be doing the coding development time estimate the above integration work. Development teams should consider the integration interface module, any changes to your ordering and billing systems, any training or new technologies that they aren’t familiar with and also time for integration testing.

Troubleshooting and Getting Help from Microsoft

When troubleshooting a CSP API integration issue use some of the following guidance to identify and resolve the issue you are seeing.

Become familiar with and handle all the error conditions from the CSP APIs. These are well documented in the MSDN documentation and most CREST API errors also return a JSON error structure with details of the error.
Get the HTTP layer REST message request and response from the code that you are running and validate that against the sample messages in the MSDN documentation. You will also need these requests and responses logged in case you submit a post to the MSDN forum or to Microsoft support.
Use the provided C# sample code and replicate the scenario with that. Do this even if you don’t regularly use C#. Replicating the scenario in this simple code base will allow you to see what REST code is sent to Microsoft when the scenario is working. Of if it doesn’t work with the sample code, you will have more information about the problem you are encountering.
Post your request on the MSDN forums and include your scenario, your code snippet, and the HTTP log of your request and response. Make sure to remove your client secret from the sign-in request if you are including that to avoid security issues.
You can use break fix support from the Partner Center web portal. This is available if you have something that you built and it was working, you changed nothing, and it appears that the Microsoft end of the integration stopped working. When you access break fix support it directs you to the Office 365 admin portal and be sure to select Partner Center APIs as the category of the support request.
You can use MPN partner benefit support incidents for API on-boarding assistance to ask for help with doing API integration.
You can also use Microsoft Premier Support hours to similarly ask for API on-boarding assistance.

CSP API Learning Resources Links

Crest Commerce APIs

Purpose: For creating and editing new customers and for provisioning new subscriptions to those customers.

Intro onboarding video: https://youtu.be/8RRssasC2Ys
MSDN Documentation: https://msdn.microsoft.com/en-us/library/partnercenter/dn974944.aspx
MSDN Forums: https://social.msdn.microsoft.com/Forums/en-US/home?forum=partnercenterapi
Code samples: https://github.com/PartnerCenterSamples/Commerce-API-DotNet/
MSDN Forums FAQ: https://www.microsoft.com/en-us/download/details.aspx?id=48218

Azure AD Graph APIs

Purpose: Partners can get a list of their customers, a list of each customer’s users, can add and edit user details, can assign Office 365 seat licenses to specific users, and can add users to the admin group such that they can use the Azure management portal.

MSDN Documentation: https://msdn.microsoft.com/en-us/library/azure/hh974476.aspx
MSDN Forums: https://social.msdn.microsoft.com/Forums/azure/en-US/home?forum=WindowsAzureAD
Code samples: https://github.com/AzureADSamples/ConsoleApp-GraphAPI-DotNet

Azure Rate card and Usage APIs

Purpose: Partners can review near real time Azure service usage data from the Usage APIs and can lookup service costs per datacenter and date range with the rate card APIs.

Overview: https://azure.microsoft.com/en-us/documentation/articles/billing-usage-rate-card-overview/
MSDN Documentation: https://msdn.microsoft.com/en-us/library/azure/mt218998.aspx
Sample code: https://github.com/Azure/BillingCodeSamples