Task 5 - A "REST" service document (July Developer Challenge - "Reverse APIs")

[qmacro]

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!

[mwn]

While my test was successful, I thought I'd investigate some of the extra activities you suggested.

I tried to use the --to mermaid option with cds compile, but I was getting an error about a missing model processor, so I thought I'd get the latest cds

After I ran

npm i  /cds-dk

I still don't have access to the model. Is there something else I need to do?

Thanks

[qmacro]

Hi @mwn 

By "still don't have access to the model" I am assuming you mean to the model processor, same error as before? 

I'm curious about the npm install command you ran, I'm assuming here that the editor / renderer on this platform has swallowed the @sap part? 

If both my assumptions are correct, then I would guess your issue is down to how you tried to update the CDS Development Kit. I don't know your local setup, but you probably want to install it globally, i.e. use the --global (or -g) option:

npm install --global @sap/cds-dk

HTH! 

[mwn]

hi @qmacro 

Once I restarted my workspace, the mermaid option worked...

[geek]

Just to prove that this task is done:

Is this a reference to CSN? Ran the following:

---

cds compile srv/plain.cds -2 "json"

---

Returning:

{
"definitions": {
"plain": {
"@source": "srv/plain.cds",
"kind": "service",
"@rest": true
},
"plain.theAnswer": {
"kind": "function",
"returns": {
"type": "cds.String"
}
}
},
"meta": {
"creator": "CDS Compiler v4.9.4",
"flavor": "inferred"
},
"$version": "2.0"
}

---

[qmacro]

Great stuff! To your question "Is this a reference to CSN?" - what are you referring to with "this"? 

[sudarshan_b]

My submission for task 5 - 

Regarding the service document, I am not sure if I am doing it correctly, but I do not see any difference between REST and OData documents when compiled in EDMX format. Am I missing something? 

Thank you.

[qmacro]

Well done for digging in and playing around, this is how we learn stuff, right? 

Remember that there's a difference between the service document and the metadata document for an OData service. The service document is at the root of the service URL, and the metadata document is at /$metadata, as mentioned in this thread. 

What I was directing folks towards was the difference between the service document when served with the OData protocol vs when served via the "REST" protocol. Try that and see what you get.

Regarding what you did (compile to EDMX), this is also nicely illustrative and we learn from that too. 

With `cds compile --to edmx` we're asking for (services and entities contained therein) in the CDS model to be compiled and emitted in an EDMX representation. This is arguably independent of how we eventually ask for the services to be, well, served (via the @protocol annotation). So regardless of whether you have e.g. @rest or @odata, the EDMX will be the same, because the services, and actions/functions/entities are the same.

[sudarshan_b]

Hello DJ,

Thank you for explaining in detail. 
I now checked the service documents (for both REST and Odata) at the root. The documents appears similar, except that the Odata document has additional attributes "@odata.context" and "@odata.metadataEtag". I also added an entity in the service.

Odata

REST

New learnings every day 🙂

Thanks again!

[M-K]

My submission:

The service documents of the REST-Service and the oData-V4 Service are pretty similar. When I try it with cat-service.cds I get a JSON-Response which contains an array with the exposed entities in both cases:

[{"name":"Books","url":"Books"}]

[qmacro]

That's right. But (as I'm sure you know), there's something missing, when compared to the same "document" when served via the OData protocol. What is that? 

[M-K]

The information that the service is an oData-Service, consisting of the "context" that points to the "$metadata" path and an etag (to check whether the metadata has changed since the last call).

{"@odata.context":"$metadata","@odata.metadataEtag":"W/\"8PKoOs3VhYwQoFzBoQObhMsFJJa5jpD1GLFcWZG9r60=\"","value":[{"name":"Books","url":"Books"}]}

But when I look into the oData-Documentation the service document should also include "functions" and not only the entity sets. Why is "theAnswer" not included for the Plain-Service there?

{"@odata.context":"$metadata","@odata.metadataEtag":"W/\"SX+YOA1v2Tu689g7VahmqbF6pmNXDWy8EHQyPjwySK0=\"","value":[]}

[MioYasutake]

My submission for task 5.

I exposed the plain service using both REST and OData protocols and compared the service documents (I also added an entity). As a result, the service documents looked similar, except that the OData document had "@odata.context" and "@odata.metadataEtag" fields. Additionally, the names of the arrays containing the entities were different: "entites" for REST and "value" for OData.

REST

OData

[qmacro]

Excellent stuff!

[AndrewBarnard]

@qmacro 

Hi DJ,  
I confess to being confused a little about the "service document" reference and how the "service document" is obtained. In this case we are working with REST and not OData, so the "service document" isn't the EDMX response returned by an OData service endpoint with $metadata appended. Is that what you meant by the service document?

The default cap "Welcome to @sap/cds Server" page shows the service endpoints, in my case, /rest/plain and clicking on this returns a JSON document containing an array of entities with no entries. The existence of functions is not described. If I add one entity to my CDS model, the JSON document contains an array of entities, with an entry for my newly added entity in the array, with attributes of name and url. The existence of functions is still not described. 

So what does cap offer that approximates the output of the OData $metadata response? cap does offer the ability to generate an EDMX description of a service defined in cap. I've found the command below useful to generate the EDMX description of the service plain:

cds srv -s plain -2 edmx

This edmx description describes both entities and functions (and types etc) , similar to that generated for OData services defined in cap.

[qmacro]

This is great, thank you (and others) for asking the question(s). I was hoping to generate a conversation with this particular task, as it's more of a navel-gazer than something practical. 

In the OData context (generally), there are two "well known" documents (resources), each with separate and well-known (predictable, fixed, relative to the base):

• the service document
• the metadata document

They are vaguely similar, and the existence of the service document, which is sort of a limited summary of the metadata document, goes back to OData's origins in Atom. See the last part of my blog post Monday morning thoughts: OData which also explains the origin of OData and by association the origin of the service document. 

These days the service document is not that useful (or perhaps I should say "not used very much") and everything revolves around the richer metadata document. By the way, in earlier versions of OData, reflecting OData's origins in Atom, the service document was also served in an XML representation by default, in contrast to how it's normally served today - in a JSON representation.

To your good observation of there being no references to functions in service documents, this again goes back to OData's origins. There was no concept of functions in the Atom Publishing Protocol (the basis for the protocol part of OData) and thus no provision for advertising them in such resources.

And yes, `cds compile --to edmx ...` is exactly what we can use to inspect the EDMX, the metadata document, for a service. This is a command line way of accessing what is actually used to generate a service's metadata document if it's served via the OData protocol in CAP.

That was a bit of a ramble, I'm afraid, but I hope it helps somewhat. If not, ask more questions, this is great!

[nidhi_m]

Submitted the task.

Regarding the service document for odata and rest services :- So the service document provides metadata about the exposed services, including the available entities, their properties, actions, and functions. In odata we access it at '/$metadata' endpoint & I don't see such service document for rest protocol exposed services. I feel it's more like interacting with the service(rest) directly via RESTful endpoints.

[qmacro]

Almost. See my answer to @AndrewBarnard 's question, which is similar. A service document is a pretty plain list of entities, not that useful, except as a "front door" to a service. A metadata document (the EDMX) is only relevant for (and only made available) for (services served as) OData.

[gphadnis2000]

Submitted the task but i m still exploring metadata difference between odata and rest protocol.

[qmacro]

"still exploring" is a good state to be in!

[mxmw]

Passed!

In regards to the service document I played a little bit around with the cds compile statement and am especially amazed how easy the OData adapter of SAP CAP is. You really only have to define the function and out of the box the services document is filled nicely, while the REST protocol has the same information but it takes more effort to get it out.

Furthemore, it seems that the REST service is not showing whether it is a bound or unbound service.

[qmacro]

Another great point / observation. On "it seems that the REST service is not showing whether it is a bound or unbound service" I would say that the concept of bound / unbound is more of an OData specific term; I would also argue that a URL path like this:

/path/to/thing/42/somefunction

is, outside of the context of OData, naturally seen as, or is expected to operate, in what we call here a "bound" fashion anyway.

[tobiasz_h]

Hello,
My submission:

And the service documents for odata and rest protocols:

Is there a metadata document for the REST protocol? Something like automatically generated OpenAPI Specification?

[qmacro]

Another great question (that I hoped someone would ask)! 

There isn't a metadata document for "REST" protocol served services, but yes, we can generate an OpenAPI definition for it, out of band.

`cds compile --to openapi ...`

Note that there are also OpenAPI specific options here: `--openapi:url` and `--openapi:servers`.

[tobiasz_h]

Good to know!
The OpenAPI specification for my plain service looks ok:

[qmacro]

That's a great idea to try out the generated OpenAPI spec in the Swagger editor, good work! 

[YogSSohanee]

Hello @qmacro ,

My submission for task 5:

I read all the valuable comments below from various participants and from @qmacro , which really helped me understand the concepts of these service and metadata document much better. Thanks a lot for that!

[qmacro]

That's great to hear, and you're welcome!

[Alpesa1990]

Hi!

Interesting exercise @qmacro !

I have created a parallel service ("plain2") and to compare both answers (rest and oData), and my conlcusion is that Odata is better in all aspacts but, is there any situation where is more advisable to use rest protocol than the Odata protocol?

My submission for task 5.

Rest

oData

Thanks and regards!

[qmacro]

Great stuff. It's a good question, and one that can only really be answered with that inevitable starting phrase, "it depends". There's a balance between the richness that OData offers, along with its well known and well documented operations, and the simplicity of a simple(r) HTTP based API. If you don't need the facilities that OData offers then a plain RESTful HTTP approach is fine.

[vineelaallamnen]

[spassaro]

Just adding some thoughts after diving a little to investigate the difference between the 2 service documents:

Rest service document: it definetely not standarized, focused on the endpoints and the methods supported.

Odata service document: has a defined, standard structure, list entity sets, functions and operations.

Does make sense?

[qmacro]

Thanks for the thoughts - and yes, absolutely. As you say, "Rest service document: it definitely not standardized" - and that's because REST is not a protocol, it's an architectural style. So by definition there is no standard 🙂

[MatLakaemper]

here my submission....

i have included the books-Entity into the Rest-Service.
Interesting, the main url doesn´t show anything, but...

when i call: 

cds compile srv/plain.cds -2 "edmx"

i receive: 

regards, Matthias

[MatLakaemper]

Hello DJ,

interesting, when i include the entity Books into the Rest-Service, the test fails.

Regards, Matthias

[qmacro]

Love the experimentation! The test fails simply because the TESTER is looking for an empty service document (i.e. no entities listed), as that's what your service should have.

[Liyon_SV]

Let's rest 😀

[Ruthiel]

Hello!

[emiliocampo]

Big thanks to @qmacro and everyone who’s been part of this interesting conversation. I’m not a pro developer, so I’m sorry I didn’t have much to add. But I’m learning a lot and hope to contribute more in the future!

[qmacro]

That's the spirit!