Task 5 – A “REST” service document (July Developer Challenge – “Reverse APIs”)

By /

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

This task focuses a little more on the plain service you set up in the previous task, and is more for us to think more about the differences and similarities between services served with the OData and “REST” protocols.

The requirements

Here are the specific requirements for this task.

If you already have the basic plain service you set up in the the previous task, then you actually have everything you need to submit a test request to the TESTER.

Why? Because this time, your submission to the tester will be to ask it to retrieve and check … the service document of your service.

As well as submitting your service to the TESTER, we want you to share your thoughts on this “service document”. What’s in it? What happens when you add an entity definition to the plain service, in the CDS model? Does it make sense to have such a service document? Does it differ from a service document of an OData service? If so, how? (Hint: Use the appropriate annotation to switch and see what happens).

In addition, here’s another aspect to ponder, and we’d love to hear your thoughts on this. OData is a fantastic example of a RESTful API. One of the well known documents that every OData service offers is the metadata document, at the path /$metadata. This is a rich (EDMX-based) description of everything that the OData service offers.

While there’s a “service document” of sorts in a plain “REST” protocol served service, is there an equivalent? What else might be useful here? (Hint: have a look at the options in the cds compile command).

Submitting to the TESTER

Now you’re ready to submit your CANDIDATE service, with the service document, to the TESTER!

The payload

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

You’ll have already done this sort of thing previously 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.

You’ll need to submit a JSON payload like this:

{
  "communityid": "<your-community-id>",
  "serviceurl": "<the-URL-of-your-service>",
  "task": "plain-serviceDocument"
}
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 (see ℹ️ A note on URLs and services). Note that the service document will be at the same URL.

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