How do I set up Custom WebApi methods?
Our WebApi supports custom methods. Custom methods must be implemented as part of the Centralpoint.WebSite.Api.Services partial class.
They also must have the following signature.
private Response Sample(dynamic request)
If you are creating your first custom method you can begin with this
Api.cs Sample.
1. Unzip this file(Api.cs) and place it in Root/App_Code either in Custom or a My_ file or folder.
2. In this file Sample method can be used as an example of how to create your custom API methods
using System;
namespace Centralpoint.WebSite.Api
{
public partial class Service
{
private Response Sample(dynamic request)
{
string warning = "";
string[] parameters = this.Method.Attributes.GetAndSplit("CustomParameters");
if (request.Required == null)
return new Response() { Success = false, Error = "Invalid Request Parameters" };
string sRequired = (string)request.Required;
int rInt = -1;
if ((request.Int == null) || !Int32.TryParse((string)request.Int, out rInt))
{
this.AppendWarning(ref warning, "Int was null so -1 was be used.");
rInt = -1;
}
string rString = request.String ?? "";
var result = new
{
AttributeParameters = parameters,
RequestRequired = sRequired,
RequestInt = rInt,
RequestString = rString
};
return new Response() { Warning = String.IsNullOrWhiteSpace(warning) ? null : warning, Result = result };
}
}
}
3. Navigate to the console Development > Web API and click the new button.
4. Type "My First Sample WebApi Call" into the Description of your Method. Please pay attention to Auto Generated Method Name. You will be using this name to call the service.*
Please change it to: "Sample-WebApi-Call" 5. For simplicity of the demo please Disable Security Mode.*
6. in the Method attribute please select Custom.*
7. Leave value Sample in Custom Method attribute.*
Api Record Setup.png
8. In Custom Parameters you can pass comma-separated values separated lists or values which can be used in your custom method.*
See line 10 in the code block of the Api.cs.
Api Record Custom Parameters.png
9. Your Custom Request is populated for you with the following values. Because of our security settings, the Token will be ignored.
{
"Token": "ACCESS_TOKEN",
"Required": "Required String",
"Int": ,
"String": "Optional String"
}
10. Custom response will show you the response of the Web API call.
{
"Success": true,
"Warning": "Int was null so -1 will be used.",
"Result": {
"AttributeParameters": [
"Parameter1",
"Parameter2"
],
"RequestRequired": "Required String",
"RequestInt": -1,
"RequestString": "Optional String"
}
}
As you can see the code block of the Api.cs show you how to validate required parameters and how to append warnings to the Api response. How to return errors or results.
To test it you can use any tool you are comfortable with.
Below is an example using "curl".
curl -X POST -d '{"Token": "ACCESS_TOKEN", "Required": "Required String", "Int": ,"String": "Optional String"}' http://YOUR_WEBISTE_URL/api.svc/Sample-WebApi-Call/
Below is an example using "PHP". This example requires a Token, list, email, URL, IP, and captureDate
<!--?php
//API Url
$url = 'http://YOUR_WEBISTE_URL/api.svc/METHOD_NAME/?r=';
//Initiate cURL.
$ch = curl_init($url);
//The JSON data.
$jsonData = array(
'Token' =--> 'ACCESS_TOKEN',
'list' => 'myList',
'email' => 'test2@test2.com"',
'url' => 'http://www.domain.com',
'ip' => '69.211.146.101',
'captureDate' => '2017-10-16'
);
//Encode the array into JSON.
$jsonDataEncoded = json_encode($jsonData);
//Tell cURL that we want to send a POST request.
curl_setopt($ch, CURLOPT_POST, 1);
//Attach our encoded JSON string to the POST fields.
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonDataEncoded);
//Set the content type to application/json
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
//Execute the request
$result = curl_exec($ch);
echo $result;
The format of the URL is:
http://YOUR_WEBISTE_URL/api.svc/METHOD_NAME/