1/ , DNN Sharp

Transcription

1 / Contents Version 1.0.0, Released Jul 4, / , DNN Sharp

2 / Contents Contents What is DNN API Endpoint?... 5 Key Features... 5 Support... 5 Getting Started... 6 Grab DNN API Endpoint Trial... 6 Place DNN API Endpoint to a Page... 6 Creating Your First API method... 7 API Actions... 8 Context... 8 Change User... 8 Inject Data... 8 Load User... 9 Data... 9 Run SQL Query... 9 Server request Send Subcribe to Mailchimp Entities Load Entities (SQL) Remove Entities Parsing Regex Payments Collect PayPal Payments Payments without PayPal account Security / , DNN Sharp

3 / Contents AES Encrypt and Decrypt Actions User User Login User Registration Update User Profile Grant User Role Revoke User Role Clear User Cache API Context API Methods What is an API What is the purpose of HTTP REST API How to create a method in API DNN Endpoint Build an API on DNN with API Endpoint API Responses Output Redirect Conditional Workflows Debugging Input Data How to Create a Field Security API Keys Cross Domain Policy API Endpoint Cross Domain Options Validation Examples How to Create an API POST method that Adds Products in an existing table with two possible results / , DNN Sharp

4 / Contents How to create an API DELETE Method to Delete a Product How to create an API GET method that Lists Products How to create an API PUT Method to Edit Products Testing with User Login and Registration actions Support Useful Links / , DNN Sharp

5 What is DNN API Endpoint? DNN API Endpoint was born to create an easy-to-use, easy-to-understand and well-tested framework for building REST APIs to help support applications that live especially outside of DNN (mobile web, native apps, syndication, other websites, etc.). It creates URLs that when invoked will execute a configurable list of actions. Key Features DNN RESTful APIs DNN API Endpoint uses REST semantics, which is a way of building applications that make full use of the web and existing tools. The benefit of this is that any app which can access the web can use the generated APIs. Configurable List Of Actions The best part is that DNN API Endpoint creates URLs that when invoked will execute a configurable list of actions. These are the about the same actions architecture that we support in many of our products. Extensions Framework DNN API Endpoint allows you to extend it with new functionality and customize it to your own needs, just the way you like it by implementing new actions. Support Our support staff is friendly and always available to help you. Engage us on our community platform. You can download latest version of DNN API Endpoint from 5/ , DNN Sharp

6 Getting Started Grab DNN API Endpoint Trial The following steps will guide you through the installation and setting of the DNN API Endpoint module. You can download it from and install it on Host > Extensions page, just as you would do with any other extension. Place DNN API Endpoint to a Page Now that you have installed this, let's start adding the API Endpoint module on a page. You have to begin by selecting the page where you want to have API Endpoint module added. When the page is opened, go in Edit Mode, click on the Modules option from the top menu - this will open the Add New Module window. Now select the Add New Module option. Find avt.dnnapiendpoint and with Drag&Drop option add the module to your page. And there you have it, the API Endpoint module just installed on the page. Note that you will need to unlock the 30 Day trial or Activate for Production before you are able to see this screen. 6/ , DNN Sharp

7 Do not worry about page or module permissions for now, DNN API Endpoint doesn't allow unauthenticated users to configure the API. But, going forward you'll have to restrict access to only administrator roles. Creating Your First API method With DNN API Endpoint you can create methods which can be invoked remotely from JavaScript or from mobile/desktop applications and so on. Below, there's a sample in which you can see how to create a method and call a web API using API Endpoint module: Action: Get a product by ID HTTP method: GET Relative Endpoint: api/products 1. Begin by adding a new method and name it (e.g. Products), set it as GET method, check the Is Enabled box. Optionally you can add a parameter in the Input Data, but the most important part is the action and response which we need. 2. As action add Load Entities (SQL) option, where we have to add an SQL Select Query (e.g. select * from [table]), set an Entity Name (e.g "Product") and set as Property the SQL Column's name you want to retrieve after executing the method (e.g. ProductId) and in Entity Property the same value as in the SQL Column ("ProductId"). 3. As response, we advise the use of the JSON Entity List (to extract all the existing records) or JSON Entity (to extract only the first record) where we have to set the same Entity Name as the one set in the action ("ProductId"). The rest is simple, just hit the Save & Test button and execute the method. According to the response you've chosen, there will be displayed on the page the whole list of the product ids registered in the database or just the first registration. 7/ , DNN Sharp

8 API Actions Summary When an API is called, it executes a list of actions Each action provides specific functionality such as sending an , creating a DNN user and so on Stack any number of actions. They are executed in the order you specify If an error occurs, the execution is stopped New actions can be added via add-ons or implemented in custom assemblies We begin with the most common example for understanding the difference between the methods in order to establish the actions which should be used according to what we want to request. When a user of a web browser enters an URL and presses enter, that creates an HTTP GET request, and when the user fills in a data entry form, and clicks the submit button, that can create either a GET or a POST request depending on how the form is constructed. The HTTP requests will be interpreted as requests for particular actions on the server and the data is returned as XML or JSON DNN API Endpoint module provides all sorts of actions which can be defined to perform a certain operation and to be executed. Most actions return an instance that derives from results, depending on the task the action method is performing. Bellow are listed all the available actions which can be used on the API Endpoint module: Context Change User This action identifies the existing user by the ID, Username or address and allows you to set up some actions so that the users can be changed. Inject Data The context is like a container where actions can read and write data. The Inject Data action can manually write data into the context and each piece of data in the context is stored under a name and can be accessed through tokens using that name. You can use this action to load data that other actions down the stack need. The values inserted into context can be constant text or tokens, including tokens created with My Tokens. When loading over a name that already exists will overwrite the existing data. 8/ , DNN Sharp

9 Load User A method is executed and runs in the context of a user action. It could be the current user performing the action or it could be the result of other actions. This action lets you manually set a user. Data Run SQL Query This action executes an SQL statement, optionally capturing the output. The SQL runs in the context of the DNN database, but there are plans to extend it to also allow a connection string or a connection string name that will make it possible to run in other databases as well not restricted to SQL Server either. This action supports context tokens and My Tokens inside the SQL query. Here are some common scenarios when you would use this action: Use an UPDATE statement to calculate some statistics for large databases on an interval, instead of calculating them on every call. Execute a SELECT statement to retrieve data to be used with other actions down the stack. Flush old temporary data using a DELETE statement. Execute a stored procedure that calculates commissions paid through a referral program. Currently, only one field can be captured from an SQL action, so make sure that your query returns the data you need on first column of the first row. We may extend this in the future to be able to store multiple columns. As a work around, either create multiple SQL actions, or produce the final text output directly from the SQL query. For example, if you need the full name of a user, you can use something like: SELECT FirstName + + LastName from Users where UserId = [UserId]. Server request This action can be used to make an HTTP request to a different server, optionally sending data. Often, this means invoking a web service. Note that if you don t run in Full Trust, this action requires that the Application Pool identity has Web Permission. The following fields can be configured: URL. This represents the URL to make the request to. A common mistake is to forget to include the protocol. For example is wrong. Instead, use Optionally, append the query string directly to the URL after the question mark. For example This field supports context tokens and My Tokens. POST Data. This is data to send to the URL using POST operation. Put key=value pairs, each on a separate line. It s also possible to post whole messages, for example and XML (that 9/ , DNN Sharp

10 SOAP-like services expect) by simply putting the XML without any lines. This field supports context tokens and My Tokens. Send This action does exactly what it says. It sends an using the SMTP server that is defined in DNN Host Settings. The following fields can be configured: From. This is the sender of the as it will appear to the recipient. Leave empty to use the system default if a portal context is set, the portal administrator is used; otherwise, the defined in Host Settings is used. This field supports context tokens and My Tokens. To. Determines who will receive the . Separate multiple addressed with semicolon. If the Determine Automatically option is used, then Sharp Scheduler tries to infer the from the Context User. This field supports context tokens and My Tokens. Reply To. When the recipient of the replies to this , the To field fills with this instead of the original From. This only makes sense when sending s to non-admin users that are likely to reply to those s. For example, it can be a trial reminder . Separate multiple addressed with semicolon. This field supports context tokens and My Tokens. Subject. Used as subject. For best experience, choose something not too short but not too long either. This field supports context tokens and My Tokens. Body. This is the content. If you need custom data then use other actions, for example the Run SQL action, to fetch it and store it in the job context. Then access it through the context tokens. This field also supports My Tokens. Attachments. This action allows you to attach up to 5 attachments to the . If a Portal Context is specified, then the file picker will show files that belong to that portal; otherwise, files from the Host folder are listed. Subcribe to Mailchimp You can use this action to submit an address to a Mailchimp list. The following fields needs to be configured so that the subscription of the address to be made: API Key - Login to MailChimp and go to Account > Extra > API Keys. Follow this link to find out more about MailChimp API Key. List Name -the list name has to be exactly as it appears in your MailChimp account. If you are not sure what MailChimp is or if it will be helpful, signup up for a FREE Trial Account and see for yourself! 10/ , DNN Sharp

11 Entities Load Entities (SQL) This action is usually used for when you want to list all or some registrations from the database, you can create a GET method with this action in order to make an SQL Select statement where you can optionally define which columns to export by setting the SQL Column with the column's name from which you want to bring the data and by setting an Entity Property. Remove Entities With this action you can remove entries by providing some criteria with which you can determine the entries you want to remove. Parsing Regex When you want to parse multiple values at once from the same Input, you can set this as action on your method. An example where we used this action, is provided on the API Methods page in this documentation, on the case where we created a method which is invoked from Server side from an HTTP request. Payments Collect PayPal Payments DNN API Endpoint allows you to set a PayPal payment requirement when the request is made. To set this requirement you will need to add the Collect Paypal Payment action. It allows you to set PayPal payments by submitting your Sandbox Account , Live Account , Payment Amount, Payment Frequency, and Currency preference. You can also apply tokens to the addresses, item title and payment amount fields. The Collect Paypal Payment action allows you to set the requirement before giving the user access to specific resources or rights. When an HTTP request is made, the redirect to the PayPal website should be made, where you should be able to complete the payment process. The user is required to log in to complete the payment process, but if he does not have a Paypal account, is required to create one. Sandbox Account The Sandbox Account field is used for entering your PayPal Sandbox address. This is the address you used when you set up your PayPal Sandbox account. Paypal Sandbox is a testing environment that allows you to test transactions without monetary transactions. You are required to enter a valid address. If you do not enter a valid you will get an error message. Live Account 11/ , DNN Sharp

12 The Live Account field is used for entering your Live PayPal address. This is the address you used to open your Paypal account. If you do not enter a valid you will get an error message. Recurring Payment The Recurring Payment drop down menu includes a list of ongoing payment options: Select None to require a recurring payment. Select Monthly to specify a monthly recurring payment. Select Yearly to specify a yearly recurring payment. Item Title The Item Title field is used for entering the title of the product or service. Currency Code The Currency drop down menu is used for specifying your currency preference, for example U.S Dollars. The drop down menu includes a list of currency preferences, displayed in the list below. Select U.S. Dollars (USD) to specify U.S Dollars as the currency preference. Select Euros (EUR) to specify Euros as the currency preference. Select Canadian Dollars (CAD) to specify Canadian dollars as the currency preference Select Pounds Sterling (GBP) to specify English pounds as the currency preference Select Australian Dollar (AUD) to specify Australian dollars as the currency preference. Amount The Amount field is used for entering the amount for the product or service. You are required to enter a valid number. If you enter letters or symbols you will get an error message. Do not enter the dollar ($) symbol, this is invalid and will return an error message. Only numbers and decimal points are allowed, for example Cancel Page The Cancel Page drop down menu includes a list of pages for redirecting the user when Cancel is selected. The list of pages in the Cancel Page menu depends on the pages available in your site. Pending Payment Page 12/ , DNN Sharp

13 The Pending Payment Page drop down menu includes a list of pages for redirecting the user when the payment is pending. The list of pages in the Cancel Page menu depends on the pages available in your site. Generate Unique Order ID If you check this option box, an unique ID will be generated for each order the users makes. Payments without PayPal account By default, PayPal requires customers that they either already have a PayPal account or create one during the checkout process. This option can be configured from PayPal so customers can buy without having a PayPal account, by using a credit card for example. Security AES Encrypt and Decrypt Actions If you want to encrypt a request, you can select this action and the key of the encryption, and optionally the fields to be encrypted as well as the stored token. The requested response appears encoded after the method is executed. These actions are the perfect options for any method that requests sensitive information, or sensitive files to servers on the Internet. User User Login This action allows you to require the user to be logged in to submit the HTTP request. There is a sort of Login template where you can link the fields created in the Input Data section to the Username and Password which have the purpose of logging the user into the existing account. Note that the fields Username and Password should be previously created in Input Data section in order for the User Login action to work. User Registration This action allows you to create a user account when the request to the method's Endpoint URL is made. To apply this action, there must be created in Input Data the same fields with the same name as in the action's drop down lists: , Username, and Password. This option is only applicable for new users. User Registration Options: Use as username Select this option to create the user account using the address provided. This option will use the address if you do not have the username field on the Input Data section. If you do not want to use the address for the user name you will need to provide the username field separately on the Input Data section. 13/ , DNN Sharp

14 Generate random password Select this option to generate a random password. This generates a random password if you do not provide a password field before making the request. If you do not want to generate a random password you will need to create a password field in Input Data. Send standard DNN registration Select this option to send the standard DNN registration . If you do not want to send DNN registration and would like a custom template, you will need to setup the actions. Update User Profile This action is used so that the users' profiles can be updated. As options, there are: Allow password update box For this option to work, you need to setup a password field in the Input Data section. This option is useful when a user would like to update his password. Also update Display Name with For this option to work, you need to setup a First Name and Last Name fields in the Input Data section so that the fields could be selected in the drop down list. This option will give the user the ability to change the display name with one of the two options: First Name and Last Name. Grant User Role Action used to assign additional roles to the user as well as to apply an expired date to each role. Grant User Role options: Role This option allows you to grant a security role. Select one from the drop down list. Other Role Names This option give you the possibility to input a role name and if you specify multiple role names, separate them by comma. It also accepts DNN tokens and My Tokens. Role expiration In this field you can input a period after how many days the role expires. It you leave it blank, it will never expire. Revoke User Role This action has the purpose to revoke the specified security role from a given user. 14/ , DNN Sharp

15 Clear User Cache This action requires an or username field and a password field to be present in the Input Data section in order to login the user. On successful login, access user info using the [User:*] tokens (for example [User:UserID] or [User:FirstName]). API Context Summary The API Context is a fairy land where all tokens and entities live All fields in the context can be accessed using token syntax, (e.g. [FieldName]) Use the context to share data between actions Input data is loaded into the context automatically The context is passed into all actions when they execute. Actions can add additional fields to the context (see Inject Data for a simple example, or Server Request and Execute SQL for more advanced ones) All fields which are created in an SQL statement (let's say column names) and which is run when we want to extract some columns from the data base, are stored as tokens in the API Context, as long as the Store As field is filled with values. To note here, that any fields created in the Input Data section, any parameters defined there, will be created and defined as tokens and stored in the API Context. Besides this, there's also this Inject Data action where we can define a value, which becomes a token. Another way to share data between actions is to use the Regex Parsing action where after defining an Input value, you just have to add a value in the Store in Token (in Regex Patter we just need a regular expression) - in order to see an example with a server request where we obtain a response stored in tokens, please check the method created on the API Methods page at Server side from HTTP request section. 15/ , DNN Sharp

16 API Methods Summary An API method is an URL that is invoked with an HTTP verb API Methods can be used to execute server side logic (actions) or retrieve data DNN API Endpoint helps build REST APIs An API method is made of 3 parts: input, actions and a response What is an API Used in the context of web development, an API is a set of HTTP request messages, along with a definition of the structure of response messages, which is usually in an XML or JSON format. According to "HTTP is a request/response protocol, which means your computer sends a request for some file (e.g. "Get me the file 'home.html'"), and the web server sends back a response ("Here's the file", followed by the file itself)." What is the purpose of HTTP The HTTP is designed to enable communication between clients and servers and works as requestresponse protocol between a client and server. HTTP defines methods, which sometimes are referred to as verbs, to indicate and specify the desired action to be performed by the client on the identified resource, which corresponds to a file. The two most used HTTP methods are GET and POST. Normally, when you open a site, that's a GET. POST is usually when you submit a form. REST API REST API is the underlying architectural principle of the web. The thing about the web is the fact that clients (browsers) and servers can interact in complex ways without the client knowing anything beforehand about the server and the resources it hosts. The key constraint is that the server and client must both agree on the media used, which in the case of the web is HTML. An API that adheres to the principles of REST does not require the client to know anything about the structure of the API. 16/ , DNN Sharp

17 Rather, the server needs to provide whatever information the client needs to interact with the service. An HTML form is an example of this: The server specifies the location of the resource, and the required fields. The browser doesn't know in advance where to submit the information, and it doesn't know in advance what information to submit. Both forms of information are entirely supplied by the server. HTTP is oriented around verbs and resources. The two verbs in mainstream usage are GET and POST, which I think everyone will recognize. However, the HTTP standard defines several others such as PUT and DELETE. These verbs are then applied to resources, according to the instructions provided by the server. GET method is used to retrieve information from a specified resource; POST method submits data to be processed to a specified resource; PUT method replaces all the current data of the target resource with the uploaded content; DELETE method removes the specified resource. How to create a method in API DNN Endpoint To create a method is very simple, first, you have to give the method a name - it will be exposed with the API and it will be also used as part of the URL to identify the created method. It should preferably not contain any white spaces. Then, you have to select the HTTP method you want to create from the drop down list displayed on the HTTP Method field. This field contains the verbs that give meaning of what this API is doing to the method. The convention for REST APIs is to use GET for retrieving objects, POST for creating objects, PUT for updating objects and DELETE for removing objects. But you are free to wire these any way you see fit. And as a last requirement, the Is Enabled box should be checked because the objects that are disabled can't be invoked from the API. All the methods accept as parameters and return them as properties and, they also accept and support tokens. These parameters which need to be fed into the API call, will be parsed under the 17/ , DNN Sharp

18 given name and it will be possible to reference the fields using the [Token] syntax. If the HTTP method is GET, then the parameters are parsed from Query String, POST is read for form data fields. Every method has it's own particularities, so make sure to read HTTP specification as well. You've already seen in the Getting Started section how a method can be created, now we're going to build something a little more complex using Action Form. Build an API on DNN with API Endpoint To get to a more complex example where we can use the integration of API Endpoint with Action Form module, below you'll learn how to create some methods which will be invoked from Action Form server side from an HTTP request action and from client side from a button. Client side request from button 1. Begin by creating and naming a POST method (we need to output some text back), check the Is Enabled box. 2. Add a text parameter field in Input Data section and name it (this will be received via query string if it's a GET operation or via POST, in our case because the method we create is a POST method) - e.g Name 3. Next thing is to create an action which will be triggered by an HTTP request and which is executed in response to this invocation - we can add a Run SQL Query action in which add an SQL Select query (e.g. select '[Name]' as FirstName) and add an Extract Column box where Column Name = FirstName and Store As = FirstName. 4. As response use the JSON Response where Name = Output and Value = [FirstName]. After you save the method, get back on the page. 18/ , DNN Sharp

19 5. Add the Action Form module on the page and select as option Blank Form where add a button, name it, and on Bind Expressions, on the section On Change/Click box add the HTTP request displayed in the sample jquery code (in order to make an HTTP request to the URL displayed in the code): $.ajax({ type: "POST", url: " data: {"Name":"Test"} }).done(function( data ) { // process response }); 6. add a text box on the form, name it and get back on the button where you just have to put the name of the text box as a token on success in the code (when running on the client side, it gets replaced with a JavaScript variable which is bound to the text box) and after the token we'll put the Output from data because the HTTP request brings back a JSON that has an Output parameter : [Textbox] = data.output; 7. We also need to call a method called refresh which notifies manually that the data is refreshed and the UI should be updated because the request/method is not cached: refresh(); 8. And last, we need to set a return false; so that the button doesn't cause a post-back. This is what the request from the button should finally look like: $.ajax({ type: "POST", url: " data: {"Name":"Test"} }).done(function( data ) { // process response [Textbox] = data.output; refresh(); }); return false; 19/ , DNN Sharp

20 9. The final step: check if this actually works - get back on the page and click on the created button. The text which should be displayed in the text box at the click on the button action is brought from the API module, all of this worked client side and it worked from jquery, it has the advantage of being called via Ajax, the page doesn't reload. Server side from HTTP request For sensitive data which is not advised to be put on the web page because the jquery calls are visible to the client browser and all the internal methods can be accessed and called by anyone. In these cases we need to make the call from server side. In order to create a server side request here's how we can manipulate the modules: 1. On the Action Form module create a new button with a distinct name in order to recognize that the action from it makes a server side request and add a On Click Handle action an HTTP request - a Server Request that makes a call to the Endpoint URL generated by the method. 2. In the URL box add the endpoint URL created by the method and in Post Data field add the data you want to retrieve (e.g. name=john) and set the HTTP method on the button as POST and set a store location by using the Output Token Name (e.g. [Name]) 3. After the request is executed, we need to send back data to the browser and we can do it by adding on On Click Handler option the Update Form Data (AJAX) which will take everything that's in the context and passes back to the browser so the UI is refreshed. 4. a small trick to get in the text box only the value and not the Output, you can add a Regex action on the button where the Input should be set in a token: [NameJson] to get a response from the HTTP request and store the data by setting in the Store in Token field the token (e.g. [Name]) and parse it using a Regex Pattern e.g. "Output"."(.*?)" - this Regex action matches the first subgroup which is used for storing into the Name token. 5. After saving these actions, get back on the page and click on the button which brings in the text box the output value from the request which is called from the DNN API module from server side. 20/ , DNN Sharp

21 API Responses Summary Although not necessary, it's good a practice to always have APIs return data Data can be JSON, XML, HTML, text or any other plain text format You can also output binary files Execution stops on first Response action in the stack After an action is completed in a HTTP request, a "202 accepted" status can be returned to the client, this response is only returned for POST, PUT, DELETE methods. This response should have only the information filled in that was available at the time the request was accepted. After the call finished, the response should include the same headers and response body informs if the the request has been finished. API Endpoint module provides the Response options which can be set and configured while creating the method according to each actions. To sum up, API Endpoint provides the following responses: Output JSON Entity Usually used on GET methods when we want to extract and list the registered values from a database, it differs from the next option at the export level, unlike the JSON Entity List which will get all the registrations according to the parameters set, the JSON Entity response, will export only the first registration from the table. JSON Entity List When this response is used, normally all the registrations from the database are listed and displayed. Raw Response 21/ , DNN Sharp

22 This response is useful for getting the response from the server and for processing data in different ways - in XML and in JSON format. It usually goes hand in hand with customizing the HTTP headers (for example, if I want to get an XML response after I set in the content <?xml version="1.0" encoding="utf-8"?> and the tags, I use the headers to determine the Name which should be "Content- Type" and the values which should be text/xml; charset=utf-8) JSON Object This response is used to return an API response usually as a "success" flag to catch if the execution of the method was successful or if it failed. The actual response data can be retrieved from the JSON Object and optionally a main response message which can be set as value in the Properties. Redirect Redirect to URL This response has the purpose to make the redirect to an external link after the request has been made. Redirect to Portal Page This response option redirects to the portal page after the the request is made and the whole source of the portal page gets displayed on the response. Send File for Download With this response option, the whole source file which was attached is displayed on the response, if there's a.css attached, the response will display the css. format. 22/ , DNN Sharp

23 Conditional Workflows Summary Fields, Actions and Validations can be dynamically enabled based on Conditions A condition is a server side C# expression that evaluates to Boolean true/false Use conditions to control the flow of execution On Input Data section, each field we add has three Condition boxes, a generic one which when is set to false it has the purpose to completely disable the field in order to not be used at all, and other two Conditions on the Validation and on the validation rules. Here you have the possibility to use tokens, let's say, that I want a field to be displayed only on mobile device, I should use a token like [Browser:IsMobileDevice] or, if I want to display a filed only on a certain browser, for example, on Internet Explorer, I have to use in Condition a token like: [BrowserIsInternetExplorer]. As for the validations, the Input Data fields have the a validation section where you can use the predefined rules we've implemented, more of this can be found on the Validation page of the documentation. 23/ , DNN Sharp

24 Debugging Summary Use the Test Method function to test APIs using jquery Alternatively, use Postman which also allows settings headers, it saves previous requests and other neat functionality Use CURL to test API from command line - it has the advantage of testing the API outside of a browser context to emulate for example mobile or desktop apps Enable Debug Mode per module or per method to collect debug information in logs Use Raw Response action to output content for debug purposes (optionally, control with this action with a Condition that looks at an input parameter) Debug client side requests using F12 Developer Tools in any modern browser The first debugging "tool" we use is the "test this method" button which is displayed in the right corner of the method - it will redirect you on the sample jquery Code page where the.ajax code is generated and the Endpoint URL is created and displayed. If the method you created is correct, then executing it will make the correct request to the web service and a response will be fetched and displayed on the page. Another tool for debugging is the Postman application for Chrome. We gave an example on the API Keys page where one of the testing methods was using the Postman application. As an additional tool, which we prefer to use when testing browser independent, is curl where in command line we make an insert like: curl --data "input=data" 24/ , DNN Sharp

25 with an already created method and after the command is run, the message which informs you about the method gets displayed, in this case, the method was created as a GET method and we've tried to insert it as a POST method. Input Data Summary Create definitions for parameters that the API acceptsbased on the HTTP Method, these will be sent via Query String or form data The input fields can be accessed inside any action using the token syntax (e.g. [ParameterName]) Input data can be validated with one or more rules Input can be text, numbers, etc - but this type is not currently used for anything, but it's required for features on our roadmap In the Input Data section text and/or number fields can be created which are used as parameters that need to be fed into the API calls. If the HTTP Method is GET, then the parameters are parsed from Query String, POST is read for form data fields. How to Create a Field You can begin by naming the field you want to create, keep in mind that the parameter name must not contain spaces and that this data will be passed to this API under this name, after which it's possible to Reference fields using [Name] syntax. This field supports also My Tokens. There are three Condition boxes where you can determine if the field will be used and how will be used in the method. The first generic Condition box has the purpose to disable the whole field, the other two Condition boxes apply as follows: one Condition box which disables the whole validation and other Condition box which disables only the validation rule. There's a validation section where you can add the predefined validation rules which will determine if and how the field validation executes, and let's not forget that this section supports My Tokens too. More about the validation rules you can find on the Validation page from this documentation. 25/ , DNN Sharp

26 Security Summary DNN API Endpoint shows generic errors for non-admins (full error is in DNN logs) If possible, always restrict API methods to trusted domains Create API keys for desktop/module/server apps to be able audit requests Use validation to ensure input is in correct format This section is created in two parts where we detail the API Keys functionality and why and in which cases is recommended to be used, as well as how to create an API Key and how to set it on a method, and two ways to test if the restriction of the web page to the key is working as expected and the Cross Domain Policy option where we provide a couple of details regarding the existing options and how they should work. API Keys API keys are used to track and control how the API is being used, for example to prevent malicious use or abuse of the API and they act as both unique identifier and a form of authentication, and will have a set of access rights on the API associated with it. An API key is submitted alongside web service requests in order to identify the origin of the request - for example, you can restrict access to certain API actions based on who's performing the request. In API Endpoint module you have the option to create and use API keys to control access to the API and also to assign an identity to various API clients. DNN API Endpoint looks in multiple places for the presence of the API Key: the Authorization HTTP header or the Query String/POSTed data/cookies for a parameter named apikey. If the API runs on the client side on same site, the API key will not be required if current user is Administrator. 26/ , DNN Sharp

27 API Endpoint has two access options, public and restricted, by enabling the public access, the data is public to any user, but if the method you created contains sensitive data, the restricted access with an API key is the best choice. Based on the key, the server identify who is making the API call in order to limit the number of requests made. So let's get to practice and let's make some tests on API Endpoint module by creating and enabling an API key on a method. First, you can begin by creating a method with which you want to obtain a list of, let's say, products. Here we need to make a GET method with a Load Entities (SQL) action where we can create a Select SQL statement from the products table, we have to define the Entity Name which will be referenced later (in the response) and we also need to create some Properties: in the SQL column set the name of an existing column from the table you previously created (in order to limit the info we want to list) and as Entity Property set the name of the column, the same values as in the SQL Column field. As response we need to set a JSON Entity list (if we want all the existing entities to be exported) in which we have to set the Entity Name which we defined in the action. After saving the updates we can go to the API Keys section (bellow the Methods) and create a key which will be set on our method in Security section. There are two ways to test if the access to the URL which was created by the method is restricted to the API key (it's the Endpoint displayed on the testing screen or you can recognize it from the.ajax call the method generates): 1. With Postman REST Client application in Chrome by sending the endpoint url of the method without key to check if the request to the method is made (as expected result, when the method is restricted to a key, it should not be accessed), in order to be accessed you must use the key as value in Headers or you can set in the requested URL as extension for the endpoint URL "&apikey=api_key_here". 2. With a browser on which you are not logged in with admin or super admin account on the website, or not logged in at all, and access the endpoint URL without the key. Here's what you should see on the screen: 27/ , DNN Sharp

28 {"error": "Current request is not authorized to invoke this API method."} The message informs you that the API method is restricted and you should use the key set on it in order to access the page. Now, if you use the key as extension to the URL, like in the example from above ("&apikey=api_key_here"), then you should have access to the method. Cross Domain Policy The Cross Domain Policy option is used to control which domains can access the API. It is useful mainly for preventing CSRF attacks and it prevents some types of content from being accessed or modified if the file exists on another domain, according to Mozilla Developer Network (MDN), this Cross Domain policy "restricts how a document or script loaded from one origin can interact with a resource from another origin." DNN API Endpoint implements two mechanisms, one which emits the Access-Control-Allow-Origin header, and the other, checks the HTTP referrer. API Endpoint Cross Domain Options By leaving enabled the default "Public" option in the Cross Domain Policy drop down list, it allows cross-domain requests from any and all domains, allows all applicable request headers and all HTTP methods. If you do not want to allow public access, the other restricted options can be used in order to give access to specific domains. You can specify a domain in its entirety when you have selected the "Restricted to list" option by providing a list of domains and/or sub-domains in the "Allowed domains" box, like site.com, or even some tokens. You can even use the asterisk wildcard to match those domains that end with the given suffix, for example *.site.com will allow subomain.site.com, another.site.com and so on. There are two other options, the "Only domains associated with current portal" option and the "All domains registered in this DNN instance" option which limit the access to the API, and here we talk about all the sites hosted in a single DNN instance and the number of domain names that those sites have. 28/ , DNN Sharp

29 Validation Summary Use validation to ensure input is in correct format Conditionally disable entire validation or specific validators DNN API Endpoint comes with a dozen predefined validators New validator can be created via config files or through custom.net assemblies The fields created in the Input Data section have predefined validation rules as well as Condition options. Here we want to make a clear distinction on the Condition fields, there are two Condition fields, one on the Validation section which disables the whole validation, and the other Condition field on the chosen validation rule, this one disables only the selected rule. 29/ , DNN Sharp

30 In the list below you can find listed all the predefined rules we've managed to implement in DNN API Endpoint module and their behavior: Date US (mm/dd/yyyy) When this rule is set on a field and the user fills in the field with an incorrect data, then the validation message, which you can put in the Message box, is displayed, informing the user that the date must be in the set in the correct format. Address When the value inserted in the address field is incorrect, the error message set in the message box should be displayed informing the user that the value inserted is not correct. Floating Point Number When this field is filled a text the error message set on the rule should be displayed informing the user that only numbers are allowed in the box. Integer Number When this field is filled with text, then the error message should be displayed in order to inform the user that only Integer numbers are allowed (negative numbers, 0, as well as positive numbers). No Funny Characters 30/ , DNN Sharp

31 When special characters like "%" or "&" are added in this box, the validation message should be displayed informing the user that these characters are not allowed. No Whitespace When this field is filled in with text with spaces between characters, the error message set in the validation message box should be displayed. Phone This field should allow only phone numbers in the format set on the field: "(###) ###-####" and other phone formats should not be allowed RegEx This field allows only regular expressions on which the validation is made. To see how we tested this validation, please check the Input Data page. Required Field This validation rule, ensures that the fields are mandatory Web Address The validation will be made on the URL structure, so if you don't insert a correct web address in the field, then the validation will be made. User exists (by ) The validation should be made on the users which are already created and the warning message should be displayed when an existing user's address is added in the field Username is available The validation will be made when the field will be completed with existing username. Examples We compiled a list of API Endpoint test cases for different methods with integration of other DNN modules like Action Form, Action Grid and URL Adapter in order to help you understand how API Endpoint module should work. How to Create an API POST method that Adds Products in an existing table with two possible results Result 1: Success - if the product was successfully added. 31/ , DNN Sharp

32 Result 2: Failed - if the product wasn't added for one reason or another.the steps you need to make in order to test this case are: 1. in API Endpoint module click on "New Method" button; 2. set an Object name > select POST as method > check the Is enabled box; 3. in Input Data section, add one/several text fields with the name of an existing column from the table previously created (e.g. Category, Price, Currency etc.); 4. add Run SQL Query action in which insert an SQL statement and a Store Scalar Result value (in which the data will be stocked, e.g. "ProductId" which is the primary key in the table) 5. add two Output JSON Object responses: one for Success where Properties Name = Success and Value = true and another for Error where Properties Name = Error and Value = "Unable to create product" (an error message in case the SQL statement fails) 6. click on Save & Test button 7. insert in Input Data fields some values and execute the code Result 1: the request should be correctly made to the web service and fetch a response: {"Success":"true"} For when the SQL Query fails the error message set as property value in the second JSON Object response should be displayed. How to create an API DELETE Method to Delete a Product Steps to follow: 1. create a POST method > name it > check it as Is Enabled 2. create a Run SQL Query action where you should insert a correct SQL Delete statement 3. click on save & test button 4. execute the code and check in the database if the values were deleted As expected result, after the method was executed, the values from the Delete SQL query should be removed from the table. 32/ , DNN Sharp

33 How to create an API GET method that Lists Products Steps to follow: 1. create a GET method > name it and check it as Is Enabled 2. leave the Input Data section empty 3. create a Load Entities (SQL) action in which insert an SQL Select Query > add an Entity Name = "Product" > add two Properties: SQL Column = "ProductId "and Entity Property = "ProductId" SQL Column = "Name" and Entity Property = "Name" 4. add an Output JSON Entity List response where Entity Name = "Product" 5. click on save &test button and execute the method The normal behavior is that the web service fetches a response in which all the values inserted in the database which correspond to the Properties set in the Actions get displayed on the page. How to create an API PUT Method to Edit Products Steps to follow: 1. create a PUT method > name it 2. add some Input Data fields named as the columns fro the database where you want to update the records 3. add a Run SQL Query action with an Update SQL statement: 4.add two Output JSON Object responses (one for success and the other for when there's an error in the SQL statement) first with Properties Name = Success and Value = true the second with Properties Name = Error and Value = error message 5. click on save & test button > add some values in the Input fields > execute the code Expected result: when executing the code with the correct SQL statement the response should be {"Success":"true"} and the existing records from the database should be correctly updated 33/ , DNN Sharp

34 When there's a failure in the Query, the error message which was inserted in the Property Value as response should be displayed and the records should not be updated. Testing with User Login and Registration actions How to create a POST method for registration Steps: 1. add a new POST method > name it 2. create Username/ /Password fields > save the actions 3. add User Registration action > select in the drop Username/Password/ drop down lists the parameters from the input data accordingly 4. click on save & test button 5. fill in the fields with valid data > execute the method After the method is executed the new account should be available and active, you can ensure if this works as expected by logging into the portal with the credentials used to create the new account or you could create another POST method in which you can use the User Login action. How? It's simple, create a POST method by going through the same steps as above, add Username Login action, set the Username and the Password fields previously added in the Input Data section; save and test the method. In the Username and Password fields you must use the credentials with which you've registered. After the "Success" message is displayed in the response, refresh the page and click on "Visit my Profile" - you were logged out from the account with which you created the method and logged in into the new account after the User Login action method was executed. 34/ , DNN Sharp

35 Support Our support staff is friendly and always available to help you. Click here to ASK US. Or contact us at: Useful Links Request support on our support forum. Purchase a new license from DNN Store. More info about Action Form at Latest version of this documentation at 35/ , DNN Sharp