Swagger UI
Swagger is an open-source software framework that aids in the design, build, and documentation of RESTful Web services based on the OpenAPI Specification. This guide provides instructions on how to access and interact with the Swagger UI, perform your first query, and execute subsequent queries.
With the Swagger UI framework, developers and non-developers to interact with the API in a sandbox UI that gives insight into how the API responds to parameters and options.
Accessing the Swagger UI
The REST API is exposed at the root of the API URL (web address). To find your URL, add "/ministryplatformapi/" after your specific domain:
https://{your platform domain}/ministryplatformapi.
A Swagger link is provided on the API landing page, or to access it directly, add "swagger" to the URL:
https://{your platform domain}/ministryplatformapi/swagger
Your First Query: Available Tables
Return all of the tables which are exposed to you through the REST API. This depends on the security roles granted to your user.
- Click GET /tables to expand this endpoint.
- Authorize use of the end-point.
To utilize the API, you must supply credentials proving you have permissions and set the scope for the end-point.
- First, click the ON/OFF button to begin the Authorization and Authentication process.
- Second, select the all scope and select Authorize.
- Third, log in to the Platform. You will be prompted for your username and password. This authorizes you to use the REST API and determine which records (Pages) you have access to (through your Security Roles).
The end-point enables if you log in successfully with the proper permissions.
- First, click the ON/OFF button to begin the Authorization and Authentication process.
- Run the query using the Try it out! button.
- Study the results.
The results display in addition to the request URL, response code, and headers. The Response Body is in JSON and lists all tables you have access to through your User permissions.
Your Second Query: Future Events
Return records for a specific table using the /table/{table}.
- Table: Any table returned by the previous query is a valid table.
- Fields: Any fields returned by the previous query are valid fields for the parent table. Any fields generated by the Advanced Search Tool are also valid, including the Table Lookup Convention.
- Filter: This is a valid SQL string representing the WHERE clause of a SQL query. Most SQL is supported here, but there are limits imposed by the API.
Example: Events
- 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"