Think Ministry supports an API Wrapper for development in the dotnet ecosystem. The wrapper uses the Client Credentials workflow, hiding all of the OAuth details and provides methods for easily interacting with the data by abstracting the REST api.
The following guide demonstrates the quickest way to consume content. It assumes development in ASP.NET using C# although there are alternate ways of consuming this data. For other approaches, see Application Development > Community Created Resources
Create or use an API Client record in MinistryPlatform for Authorization. You will need the Client ID and Client Secret from this record to use the Client Credentials OAuth workflow. The details of this workflow are hidden by the wrapper.
If you don't want to use an existing API Client, you can create one by following these steps
Together with the Client ID, the Client Secret is used to access the API. They are like the API login and password. The secret should be very secure. A simple way to do this is to use a guid generator.
The Client User determines the permissions available via the API. Typically, this is "API User" unless a permissions need to be more restricted for the API Client.
See: API & Identity Pages
In your ASP.NET project, add the api wrapper Nuget package:
PM > Install-Package ThinkMinistry.RESTAPIWrapper
This package provides a very simple wrapper around the REST API and OAuth2 implementations. It removes the need to work directly with OAuth, tokens, authentication, etc. It provides an easy to configure system that relies on client credentials to use the api.
The Nuget package adds the following folders and file:
First, rename the localhost folder to match the domain you will be hosting. For example, if your application will be running at the domain "https://app.fantastic.com/" then you would rename this folder "app.fantastic.com"
Next, edit the customer.config file
The _RESTAPIWrapper folder has a readme file which may be helpful getting you started using the library. You can delete this folder and file when you are done with them.
First, create and initialize a query object. A query without a table will return a list of tables and fields.
The query can specify a table, fields and other parameters. Omitting fields will return all table fields. You can use field aliases to rename fields. Here is a simple example which returns approved future Events.
var query = new APIQueryRequest { Table = "Events", SelectFields = "Event_ID, Event_Title, Event_Start_Date, Event_End_Date, dp_fileUniqueId AS FileID", Filter = "Event_End_Date < GETDATE() AND Cancelled = 0 AND [_Approved] = 1" };
Second, retrieve the results using an api client.
var apiClient = PowerApi.CreateWebApiClient(); var results = apiClient.GetCollection(query);
When using the retrieved data, you can use the dynamic objects exposed by the wrapper, or cast them to strongly-typed objects if you prefer.
@foreach (dynamic item in results) { <li>@item.Event_Title.Value</li> }
If you would like to use Strongly Typed objects rather than dynamic, cast to POCOs using the api client's DynamicListToType method. Here is an example for Events:
results = apiClient.GetCollection(query); IEnumerable<Event> events = apiClient.DynamicListToType<Event>(results); @foreach (Event event in events) { <li>@event.Event_Title.Value</li> }
To update, apply changes to an object you’ve returned from the api. Here, we are using a dynamic object.
item["Participation_Status_ID"].Value = 3; //Attended
Create an Update request.
var update = new APIUpdateRequest();
Specify the record and table name. To update multiples, use the Records collection.
update.Table = "Event_Participants"; update.Record = item;
Update and return the result using the PutRecord method of the api client. The result will be an updated copy of the record.
var result = apiClient.PutRecord(update);
First, create a dynamic object with the properties you want. This example makes use of a Donation POCO.
Donation donation = new Donation() { Donation_Amount = (decimal)amount, Donor_ID = 1467, Payment_Type_ID = 1, Receipted = false, Donation_Date = donationDate };
Then create a Create request.
var create = new APICreateRequest(){ Table = "Donations", Record = donation, SelectFields = "Donation_ID" }
Create and return the result using the PostRecord method of the api client.
var result = apiClient.PostRecord(create);
The Select Fields can be retrieved from the result:
donation.Donation_ID = result.Donation_ID;
To further explore the API Wrapper, a sample app is available. The samples can be downloaded and run from this repository: https://github.com/MinistryPlatform/WrapperSample.