There's a few things you do need to know while using the API Designer and the
best way to learn those things is through a simple example. So, say we want to
create an API called Fix it Fast
Incident Report.
We add an API name, which becomes part of the URI for the API,
a quick description ...
Click Create. Done.
Now, as a mobile app developer you're creating the interface to the API, or the
contract that describes the API's correct behavior. Someone else is probably
writing the implementation that actually goes after the data. Anyway, if you're
just describing the data you need for someone else to implement, the only thing
you really need to pay attention to here is the Endpoints tab.
An "endpoint" is just a noun called a "resource", and a verb called a "method".
A single API usually has multiple endpoints to describe the data you need
and what you want to do with it.
So let's see how to add a resource ...
We start with a noun - in this case, "incidents". Say this API is for an app
that lets homeowners request service from a company called Fix It Fast, so
that the homeowner can get someone to come out and fix a leaky water heater, or
some other appliance problem.
Each request is in the form of a service incident.
We want the API to be able to fetch all the service incidents out of the backend
system, like, say Oracle Service Cloud. Now we need a verb, so we click Methods.
We want the verb "GET", so we can get all the incident reports currently in the system.
The endpoint "GET incidents" will do just that.
There's nothing else we need to worry about on this page right now, so let's go
back to the Endpoints page. Say we also want to be able to retrieve a SINGLE
incident from a system, based on the incidents unique ID. To do that, we'll add a
"nested resource".
A nested resources is useful when you want to zero in on a subset of a larger
resource.
The plus sign lets you add nested resources. We'll add a nested resource
called ID based on the parent, "incidents". You know that it's nested because it's
shown AFTER the parent resource, which is highlighted in gray.
We need a GET method for this endpoint too, of course.
In a few moments, you'll want to test this endpoint to make sure you're going to
get back the data you expect.
You could click TEST now and take the steps to get a simple 200 response back,
which means the call is successful, but let's make things a bit more interesting by
supplying some mock data. This will make the endpoint behave more like it will
when it's actually implemented.
All you have to do is cut and paste some JSON into the API Designer like this:
Click Responses.
Then Add Response.
Click Add Media Type.
Click Example.
And paste the JSON snippet.
That's it!
We have two endpoints now for our API, so let's not add any more - you get the idea of
how to do it.
Now let's test the endpoint that has the mock data, that is, the GET
incident/{id} endpoint.
The first thing you need to do is go to the Security tab and allow anonymous
user access.
You probably wouldn't do this in real life, you'd probably enter a role that
pertains to your mobile users, but for testing purposes it's fine.
Before you can test an endpoint in MCS, it has to be associated with a mobile
backend.
A mobile backend allows you to develop and deploy groupings of APIs that are
designed to support a specific set of applications. In this case, we're
developing our API in a mobile backend called Fix It Fast, so we'll select that.
Voila! Check out the Response!
Now you've got some well-formed JSON, with proper data, mimicking what will
eventually come back from the implemented API.
By defining many endpoints and supplying mock data like this, you can build up an
entire "mock API" to code against - so you can do some rapid prototyping WITHOUT
having to wait for the API to actually be implemented in JavaScript.
You now should have enough information to go off and write your own API in the
API Designer.