Reading through GoDaddy's domains endpoint documentation ( https://developer.godaddy.com/doc/endpoint/domains ) am trying to use GoDaddy's API to update DNSSEC records (DS records to be more precise). Very few examples (found none actually) are out there showing how to actually do that.
The above documentation does seem to mention a "model" called DomainDnssec (same URL as above) which does refer to values and their types that need to be either POST'ed or GET'ed using one of the API URLs but it's not clear to me which one. What is "model" in that context anyway (literally just a description of data types that have to be posted or received using particular API endpoints? this is not clear to me either and documentation is silent about that)?
As much as I do not have an issue with using API in general (all set up and working, together with finding out infamous customerId which most folks confuse with shopperId), I'm having a hard time finding which API call allows interacting with DNSSEC on GoDaddy's API.
I did not try much yet as none of the actions (API calls) within the API domain namespace documentation seems related particularly to DNSSEC.
===an update
It seems that in the Action model (https://developer.godaddy.com/doc/endpoint/domains#/), there is a reference to API calls that do not seem to be documented:
DNSSEC_CREATE - Request to create DNSSEC record for the domain via PATCH /v2/customers/{customerId}/domains/{domain}/dnssecRecords
DNSSEC_DELETE - Request to delete DNSSEC record for the domain via DELETE /v2/customers/{customerId}/domains/{domain}/dnssecRecords
Not sure why this call is not explicitly documented among other v2 API calls. An overlook? Still not sure how to build API calls allowing to update DNSSEC records.
Related
Our LinkedIn API calls started failing. Even the simplest /v1/prople/~ calls started erroring with This resource is no longer available under v1 APIs.
So we're trying to migrate stuff using the new /v2 way, but somehow it seems not to be working. For example (and after requesting a token with the new scopes), a simple request to /v2/me fails to return the fields we need (amongst others, headline and location). When asking explicitly for these fields, we're told that we don't have access to them - even tho the token was generated using the r_basicprofile r_liteprofile r_emailaddress scopes.
We've tried numerous combinations and variations of asking for certain fields, projections, formats, etc from the Microsoft docs - with no avail and we're wondering whether the /v2 API is actually something functional - is there anyone successful using it, and if so, how?
A sample CURL request with an obfuscated Bearer would be a good way for us to understand what we're doing wrong - but it seems that even the simplest requests verbatim from the docs just fail.
EDIT: After some research, it looks like Microsoft changed their versioned API behavior without being consistent in the docs. Some docs point to r_liteprofile and some others to r_basicprofile as the default way to go now without being "Linkedin Partners". We were previously requesting r_emailaddress too and the headline and location parts of the r_basicprofile bits were used in our code in many different places.
These were two problems:
Some of the fields are removed from v1 (headline, email, location etc),
Most of the fields requested are not available in v2 without special scopes, but these scopes are very poorly documented as being part of a "LinkedIn Partner" program our app has to be accepted in before we can now use them.
The basic answer to this question is that LinkedIn (Microsoft) made backward-incompatible changes to their API.
I still don't understand how the client knows what data to POST when creating a resource. Most tutorials/articles omit this and in their examples, a client always seems to know a priori what to post (i.e. using out-of-band information). Like in this example, the consumer knows that he has to place the order by setting what <drink\> he wants.
I can only image a few approaches and I don't know if they are valid:
1. Returning an empty resource
The client discovers a link to /resource with a link to /resource/create and relation "create". A GET to /resource/create returns an empty resource (all attributes are empty) and a link to /resource/create with relation "post". The client then sets values to all attributes and POSTs this to /resource/create which returns a 201 (Created). This means that the CRUD operations are not located at the resource endpoint but to URI like /resource/create and that the client might set attributes the server ignores (like a creation date which is set on the server side)
2. Returning a form
Basically the same approach as above, despite the fact that not a resource is returned but some meta-information about what fields to post and what datatypes each attributes needs to have. Like in this example. Still, the creation endpoint is not located at /resource but on /resource/create
3. Creating by updating
A POST to /resource immediatly creates an empty resource and returns a link to this resource. The client then can follow this link to update the resource with the necessary data doing PUTs.
So what is the best approach that still follows the HATEOAs paradigm and why are all of these tutorials (and even books like REST in Practice) omitting this problem?
UPDATE:
I recently found out the Sun Cloud API seems to be pretty close to an "ideal" REST HATEOAS API. It not only defines some resources and does hyperlinking between them, it also defines media types and versioning. With all this theoretical discussion, it's pretty good to have a concrete exmaple. Maybe this helps some readers of this question.
Most tutorials and books about REST are very misleading, because there are many misconceptions about REST and no authoritative source other than Fielding's dissertation itself, which is incomplete.
REST is not CRUD. A POST is not a synonym to CREATE. POST is the method to be used for any action that isn't already standardized by HTTP. If it's not standardized by HTTP, its semantics are determined by the target resource itself, and the exact behavior has to be documented by the resource media-type.
With HATEOAS, a client should not rely on out-of-band information for driving the interaction. The documentation should focus on the media-types, not on the URIs and methods. People rarely get this right because they don't use media-types properly, and instead document URI endpoints.
For instance, in your example, everything has the application/xml media-type. That's the problem. Without proper media-types, there's no way to document resource-specific semantics when everything has the same media-type without relying on URI semantics, which would break HATEOAS. Instead, a drink should have a media-type like application/vnd.mycompany.drink.v1+xml, and your API documentation for that media-type can describe what to expect when using POST with a rel link.
I have read a few articles about HATEOAS and the way that API should be implemented such that you can traverse to different states by following the links. But I'm confused as to how the client should be implemented?
From this answer:
The client knows nothing about how the server designs its URIs other
than what it can find out at runtime.
Does the client need to crawl from the root node down to a nested resource to just make a POST if it doesn't know the direct URI?
What would be the purpose of API documentation then?
For implementing HATEOAS server needs to include links to responses that goes from server to client, and client uses these links in response to communicate to server.
For eg. Client request Product list, server will respond with list of products with link to Add, edit and delete the products (if user is able to do that), which will then be transformed in client into links or buttons like Edit Product, Delete Product.
This blog might help you get more understanding.
Does the client need to crawl from the root node down to a nested resource to just make a POST if it doesn't know the direct URI?
Yes unless the root page does not contain the link which describes the POST.
What would be the purpose of API documentation then?
It describes the metadata the client can recognize for example by a link or by a property. So it describes the capabilities of the service.
To answer your first question "Does the client need to crawl from the root node down to a nested resource to just make a POST if it doesn't know the direct URI?"
The answer is No. The client always does not have to crawl from the root node. It is possible to design the URI;s such a way that the navigation to reach the direct URI can be from other views. For example if the purpose of the URI (/Products/product1/Delete) is to delete product , then it should be possible to reach this by either crawling from the /Products or by giving a namespace query of Products/Deleteview. This "DeleteView" URI should give all the URI's of the delete view. i.e it can return a uri collection like Products/product1/Delete, Products/product2/Delete etc.
To your second Question "What would be the purpose of API documentation then?"
Concept of API is a legacy of the past. Ideally the URI itself should be the documentation. This way the client can be programmed to discover and take only things that it can respond to.
We got hold of unique technology which manages these namespaces. so we are shielded from this view manipulation ourselves. I recommend using a technology to manipulate and create these URI namespaces.
Here is an excerpt from an assignment I am currently doing:
Build a dummy app that:
Contains a REST API that operates over a single resource.
Contains a Backbone client that consumes that API and can list, show, create, update, and remove that resource.
My understanding was that the term "consume" implies total coverage of the API's exposed ressources. However, the assignment says "consumes that API and can [CRUD] that resource".
Is that sentence redundant or is my understanding of the term wrong?
(Bonus question: why searching Google for this question returns countless language-specific tutorials for "consuming an API" but none explain what the term actually means?).
To consume an API means to basically use any part of it from your application.
Consuming an API here means creating a client which can send requests to the API that you build.
It appears that you need to create and API which can handle Create, retrieve, update and delete (CRUD) of a resource. For instance if your REST api is to create a blog, your API should handle CRUD functions for the object/resource blogpost.
POST - Create a blog post
GET - Retrieve a blog post
PUT - Update a blog post
DELETE - Delete a blog post.
It is about the direction of the app's interaction with API - it either provides an API, or consumes it, so there are providers and consumers of API, and this is just a less general and ambiguous term than 'using'.
Simply consuming an API means using it in your application.
For, e.g., GET request to https://someapi/Users will give you all the users.
You need to request this URL https://someapi/Users to get all the users and then you can use it into your application.
I always think about Albert Einstein's quote of "If you can’t explain it to a six year old, you don’t understand it yourself." when someone asks a question that you might take for granted due to technical experience you have on a subject.
I think the following medium.com article does an excellent job explaining it: How do you explain API to a 5-year-old?
simply means : using the API.
You can do it with HTTP method (GET, POST, PUT, DELETE..) using something like Postman (Tool) or maybe you have a client app/library that calls these methods implicitly.
I'm building an API centric web application.
Our frontend will consume the API and after testing our plan is to release the API to the public.
I'm faced however with problems that in a normal MVC application were pretty straight forward but I can't seem to wrap my head around it in a RESTful way.
Take this example for instance:
A company has multiple office sites which point to a specific address
This address can be shared by multiple sites so Company has a one to many relationship with sites and sites has a many to one relationship with Address
When you update an address I'd like to let the user confirm that for that they either want to update the LOCATION (so all companies that share that location through Site will be updated) or they just made a typo and want to create a new Location
How would I go about this in a RESTful way?
I can do a
I first do a GET if there are other companies using that location
Then I give the user a choice either to do POST (create new location) or do a PUT (update location)
In case of POST also create a new Site linking the new location to the Company.
An other example is if what appears a single form for the user will invoke several different backend entities that have to update.
Any examples or ideas?
In REST, you might thing of the remote service as being the database. If you know how to do it in a generic MVC workflow, for fat-client apps it's the same.
You may want to deal with it on a "try default behavior, and raise attention if not possible" way, or with a "check what's possible and then offer possibilities". It's your app, it's your choice.
Personally, I'd go with a "try default and raise error if edge conditions happen". So in this case, assume (in the client) there is no other company with the same address, and use the corresponding endpoint (PUT). If the server detects a possible conflict, then return some error. The client will then prompt to the user what to do, and use whatever endpoint is chosen (POST or PUT, with a flag that enforces the update)