REST URL Variables
In the REST Wizard, when you come to the REST Service URL step, there is a field where you can enter your REST URL. You will see placeholder text reading "Enter your URL - place variable(s) in {braces}" - what does this mean?
One of the benefits of REST is that the data is stored in a database and not on any client (such as a mobile phone). The client only gets the data it needs when it needs it (by using a REST call).
For example, let's say you have a database with a list of your company's employees and you want to create an app with a company directory. You could have one big list of every single employee, but it might make more sense to divide them by department. In that case, you would need a REST call that will only return employees of a single department. So does that mean that if you have 15 departments, you will need 15 separate REST calls? Not exactly - this is where variables become useful.
Sometimes it can be useful to think of a REST call like an instruction that your app can give a database. For example, you might want to give it the instruction "Give me all employees". In our department example, you would want to give it the instruction "Give me all employees in department Sales", "Give me all employees in department Management", etc. Using variables allows you to use a single instruction, like "Give me all employees in department X", to cover multiple scenarios.
In the MobileSmith platform, you indicate a variable by wrapping it in curly braces {} - think of it as the 'X' part of the instruction.
"id" is one of the most common variables used in REST. In a REST database with employees from different departments, it would make sense to have a way to identify each employee's department. Since the name of a department could change over time, it would make sense to assign each department a number that never changes - this is the "id" field.
Each employee could have a field "departmentId" that corresponds to the "id" field of the appropriate department. For example, if the Development department's id field is 54d3bed8f6895c5936cc4508, then every employee who is in Development should have a field "departmentId" that is 54d3bed8f6895c5936cc4508.
So you could use a REST call that returns all the employees in Development, and it might look like this:
http://52.0.142.191:80/api/departments/54d3bed8f6895c5936cc4508/employees
You can certainly do that, but then you would need to repeat the process for every department. A better way would be to use a variable for the department's id field:
http://52.0.142.191:80/api/departments/{id}/employees
After entering this URL in the platform, click the green "Check for Variables" button. This will allow you to enter a sample value for each variable:
Executing the raw URL will not return data, because the REST database will not understand the "{id}" part. It would be like giving the instruction "Give me all employees in department X" - the database (if it could talk) might say "I don't know which department you mean." The sample value allows you to specify a certain department.
This is why you must enter a valid sample value - the platform will replace the variable part of the URL with the sample value. Let's say you enter 54d3bed8f6895c5936cc4508 as the sample value for id. When you click the blue "Send" button, the platform will execute this URL:
http://52.0.142.191:80/api/departments/54d3bed8f6895c5936cc4508/employees ("Give me all employees in department 54d3bed8f6895c5936cc4508")
instead of this one:
http://52.0.142.191:80/api/departments/{id}/employees ("Give me all employees in department X")
Below the Send button, you will see the actual URL executed and the data returned - this lets you verify that the REST call is returning the correct data.
Is that it? Almost. The final step is to give the app user a way to choose the department. In this example, you would make a List page for departments and use a REST call (with no variables) that returns all the departments:
Next, you would make a List page for Employees and use a REST call with a variable for the department id.
Finally, you would connect the two pages and tell the platform to take the id of the selected department and use it to replace the {id} part of the employees REST call. Click here to see how to connect pages.