API Wrapper

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

1. Authorization

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.

Creating an API Client

If you don't want to use an existing API Client, you can create one by following these steps

Navigate to Administration > API Clients
Create a new record
Enter a Display Name, Client ID, Client Secret and Client User

A. Client ID and Secret

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.

B. Client User

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

2. Add REST API Wrapper to your project

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.

A. Configuration

The Nuget package adds the following folders and file:

_DomainData (folder)
localhost (folder)
Customer.config (file)
_RESTAPIWrapper (folder)

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

OAuthClientID — The Client ID from the API Client record
OAuthClientSecret — Client Secret from the API Client record
OAuthBaseAddress — Enter the discovery endpoint for oauth. This is will be the location of your MinistryPlatform installation with a subfolder named oauth. Visiting this url in a browser should give you back a chunk of JSON starting with the issuer. To find this url, see OAuth 2.0 > Discovery.
ServiceAddress — The location of the api for your MinistryPlatform installation. Normally, this is the same as your platform url with “api” at the end. Visiting in a browser should display a Platform REST API Test Page. To find this url, see REST api.

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.

3. Reading Data

A. Query

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"
};

B. Results

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>
}

Strongly Typed Objects

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>
}

4. Writing Data

A. Update

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);

B. Create

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;

5. Sample App

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.

Knowledgebase
- Develop