Task 2 – Capire’s Hello World! (July Developer Challenge – “Reverse APIs”)

By /

This is a task in the July Developer Challenge – “Reverse APIs”.

This task is to add a second API endpoint to the service you already created in Task 1 – Your first service and first endpoint. It’s nice and simple, and in fact is rather similar to the “Hello World!” example in Capire‘s “Getting Started” section (“Capire” is the friendly name for the CAP documentation). After you’ve completed this task, why don’t you head over there and take a look around, as documentation goes, it’s really rather awesome.

A second API endpoint in the “basic” service

To complete this task successfully, all you have to do is implement another API endpoint and make it available in the service you created in the previous task, and of course submit it to be tested by the TESTER. That means adding that API endpoint definition to the service definition in your CDS model, and then writing the implementation for it.

The requirements

Here are the specific requirements for this task.

The API endpoint should be made available within the existing service basic. Relative to the service path, the name should be hello and be requestable via an HTTP GET method.

It should have a single parameter, to, and should return a String value, in the context of a JSON payload that looks like this:

{
  "@odata.context": "$metadata#Edm.String",
  "value": "Hello, <value-of-argument-passed-to-the-to-parameter>!"
}
All this means is that you should declare and implement this API endpoint as an unbound function in the context of your existing service that is being served with the (default) OData V4 protocol.

🚨 Finally, be aware that the service should be served at the path /basic, and NOT at the path that’s default for OData V4 services (which would be prefixed with /odata/v4). This was actually a requirement in the previous task – Task 1, but the TESTER was deliberately set to “lenient” mode for your very first API endpoint task. That “leniency mode” has been turned off now 🙂 So you may find yourself having to adjust your service so that it’s served specifically at the /basic path. You may find the cds.serve() – @path section useful here.

When this API endpoint is added to the service and served via the OData V4 protocol, the service metadata document should look like this:

<?xml version="1.0" encoding="utf-8"?>
<edmx:Edmx Version="4.0" xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx">
  <edmx:Reference Uri="https://sap.github.io/odata-vocabularies/vocabularies/Common.xml">
    <edmx:Include Alias="Common" Namespace="com.sap.vocabularies.Common.v1"/>
  </edmx:Reference>
  <edmx:Reference Uri="https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Core.V1.xml">
    <edmx:Include Alias="Core" Namespace="Org.OData.Core.V1"/>
  </edmx:Reference>
  <edmx:DataServices>
    <Schema Namespace="basic" xmlns="http://docs.oasis-open.org/odata/ns/edm">
      <EntityContainer Name="EntityContainer">
        <FunctionImport Name="ping" Function="basic.ping"/>
        <FunctionImport Name="hello" Function="basic.hello"/>
      </EntityContainer>
      <Function Name="ping" IsBound="false" IsComposable="false">
        <ReturnType Type="Edm.String"/>
      </Function>
      <Function Name="hello" IsBound="false" IsComposable="false">
        <Parameter Name="to" Type="Edm.String"/>
        <ReturnType Type="Edm.String"/>
      </Function>
    </Schema>
  </edmx:DataServices>
</edmx:Edmx>
You can see that this metadata document contains definitions for two FunctionImports “ping” and “hello”.

Once you’ve got your service defined, and a simple implementation ready with an on handler for the hello event, you’re ready.

It is definitely worth testing it yourself first, e.g. with curl, Postman, or even the REST Client extension to VS Code that some of you are using (going on what I can see from some of your responses to the previous task). Use whatever tool you prefer for making HTTP calls.

With your server running (on, let’s say, the default local CAP server port of 4004), make a request like this, supplying a value for the to parameter:

curl -s --url "localhost:4004/basic/hello(to='Zaphod')"
and the reponse should look like this:
{"@odata.context":"$metadata#Edm.String","value":"Hello Zaphod!"}

Submitting your API endpoint to the TESTER

Now you’re ready to submit your CANDIDATE service, with the specific API endpoint, to the TESTER!

The payload

The task identifier you need to supply in the payload of your submission is: basic-hello.

You’ll have already done this sort of thing in the previous task so just head back there for the more detailed instructions if you need them, or to the the section titled “The Tester service, and making a test request” in the main challenge blog post.

Now, to have your freshly minted API endpoint in this task tested, you’ll need to submit a JSON payload like this:

{
  "communityid": "<your-community-id>",
  "serviceurl": "<the-URL-of-your-service>",
  "task": "basic-hello"
}
Note that the TESTER will pick a value for the to parameter, of course, and send it in the test call to your API endpoint.

And, just as with the previous (and all further tasks):

  • the value for the communityid property should be your ID on this SAP Community platform (e.g. mine is “qmacro”)

  • the value for the serviceurl property should be the absolute URL (i.e. including the scheme), of your CANDIDATE service which contains the API endpoint (see ℹ️ A note on URLs and services), not the full URL of the specific API endpoint itself

That’s it!

Logging of test results

Remember that you can check on your progress, and the progress of your fellow participants – all requests are logged and are available in an entity set served by the TESTER service. The entity set URL is https://developer-challenge-2024-07.cfapps.eu10.hana.ondemand.com/tester/Testlog and being an OData V4 entity set, all the normal OData system query options are available to you for digging into that information.

Until the next task, have fun, and if you have any questions or comments, leave them below!

Scroll to Top