When creating an instance of REST API (an application), a version (appearing as a prefix) has then to be included in the URL when calling it.
Is there a way to manager several versions (at the same time) of an API? Are we able to change the version number or how is it changed?
The only link I have found is : https://docs.marklogic.com/guide/rest-dev/intro#id_64988
But it is not pretty clear to me.
Thank you for your help
As the link says, "The version number is only updated when resource addresses and/or parameters have changed. It is not updated when resource addresses and/or parameters are added or removed."
In other words, the REST API will increment the version step if it ever becomes necessary to rename or restructure the addresses of resources. Ideally, that will never need to happen. If incrementing becomes necessary, the goal will be to maintain a deprecated interface if possible at the old address for one release.
In addition to David's good suggestion, you could also build your own version numbers into the name of the resource service extension if it's better to support multiple versions of an extension in a single modules database.
If this is to have versions of your rest extensions and use the V# in that process, then I think you could have multiple sets of your code deployed in different modules databases (per version) and dynamically switch modules database based on the version and then rewrite the URL after that to play well with MarkLogic's REST API.
http://developer.marklogic.com/features/enhanced-http
Related
I have a project to maintain the user and his/her project allocation records. The project exposes REST APIs to support user/project CRUD operations.
The REST endpoints are designed to support backward compatibility using REST API versioning so that any new changes in the REST API should not affect the existing consumer of that API.
I have the below use case where I need suggestions for the best approach:
At first, the business requirement was that a user can be deleted irrespective of his/her allocation to some project and hence the REST API to delete the user was created with version v1 to support this.
But then there was a change in the requirement that a user cannot be deleted if he/she is allocated some project.
This is a change in business validation. Should I create a new version(v2) of user DELETE REST API to support this business validation or I should add this business validation to the existing version(v1) of user DELETE REST API?
My viewpoint:
If I will expose two versions of the user DELETE REST API then the database can have records with deleted users with as well as without project
I would argue that this is more of an implementation detail of the backing store. In all likelihood, the storage mechanism for both is almost certainly the same.
I would not change the DELETE API nor version it because the contract is 100% the same over the wire. A client has no idea how it's implemented behind the scenes; they're not supposed to anyway. The implementation needs to change such that a DELETE always results in a soft delete after some point in time (e.g. when you publish the new version). If you version DELETE you also open things up where clients can do things you don't intend; for example, triggering a real deletion by using a specific version of the API.
The thing that needs to change is how the older APIs deal with all of the other supported methods such as GET, POST, PATCH, and so on. The older APIs should yield 404 for a soft deleted resource (implying that DELETE was permanent). POST is probably the most unusual case. This could return 409, but that implies the resource exists or it could result in an update that also undeletes the existing resource. This API would likely even continue to return 201, implying the resource was created when it was really just updated in storage.
Remember that Representational State Transfer is just a representation of your business logic. Keep the APIs the same (and thus clients from breaking) and adjust the implementation to adapt to new rules. The DELETE API is unchanged (and usually version-neutral). Clients don't know what the man behind the curtain is doing. If things continue to behave the same over the wire, clients are none the wiser.
I hope that helps.
Is there's a way to update the nextBuildNumber directly via Rest? I found the parameter here:
/job/MyJob/api/xml?tree=nextBuildNumber
and in the job directory, there is a nextBuildNumber file
We already use the Rest Api for creating/updating jobs and views, so it would be nice to stick to this, instead of using cli or the nextbuildnum plugin.
Edit: new approach brings another question
Java send integer value with HTTP POST
The REST API does not currently (at time of writing) support changing the value of the nextBuildNumber. As you have found you can (only) read it.
The easiest way I know to manipulate this value is through the Next Build Number plugin.
For our Web api project we use the following url versioning system:
https://{fqdn}/{apiVersion}/{apiResourceName}/{resourcePath}?{parameters}
for instance we can have something like the following:
https://myapi.mysite.com/v1/customer/2
Now considering above, let say you want to release two versions (live,test) to the customer. One live version (working with live data) and the other one is the test (working with test data for customer development test).
For live one I could easily use the one I mentioned : https://myapi.mysite.com/v1/customer/2 .
How do you name the test version of the above api? what is the test version of a api url version v1? Can specify the test api url?
Also what are best practices for fully qualified domain name of the API {fqdn} when using url versioning?
There are really several ways to do this.
One way, for instance, is to simply use attribute routing to give it a different path. Create a separate method, give it a path of /vtest/customer/2 for example and if users access this /vtest/ version (or v2 or 3 or whatever) then return the test data/new version. See an example in this question
Another way is to host your "test data" API in a different application in your server and have your web.config point to test versions of your database/source data. Using IIS, you'd configure two different applications (one for test, other for live) and the base URL would differ e.g.: https://myapi.mysite.com/appname1/v1/customer/2 vs https://myapi.mysite.com/appname2/v1/customer/2 and your appname could be something like live vs test. Have a look at this simple example
You could also just host them in different servers altogether, which would result in your {fqdn} changing between test and live versions (e.g. server.com/v1/customer/2 vs testserver.com/v1/customer/2) - this is what I do at my current job, and I find it very effective as it isolates live/test data (and API versions) avoiding confusion between them.
I also found this blog post detailing how to do this with namespaces
In other words there isn't just one best/correct way to do what you want, it all boils down to how you (or your company/boss/team) wants to structure and control test vs live data in your APIs. Take a look at these options to see which one is best in your case, hope I was able to help.
I think the title of your question is misleading. The problem you are trying to solve is not versioning (because your client is connecting to the same version of your application: v1). It is about having multiple environments: one for live data and one (or more) for test data.
At my company we solve this issue through the host name. At https://live.mysite.com/api/v1 we host v1 of the API connected to live data. At https://nodex.mysite.com/api/v1 we host v1 of the API connected to test data. Our clients can request new nodes as necessary (e.g. client1-devnode.mysite.com/api/v1 to develop against, and client1-testnode.mysite.com/api/v1 to test against. Each node get it's own set of test data.
Most of the live projects different server for different environments.
Instead of using different version of API endpoints, You should use different servers for different environment like this :
For Prod/live : https://myapi.mysite.com/v1/customer/2
For Test : https://myapi.mysitetest.com/v1/customer/2
For Dev : https://myapi.mysitedev.com/v1/customer/2
You need to configure environment specific properties for different backend endpoints you are hitting. Like : test.properties/dev.properties/live.properties
With my experience in API developing i found that there are 2 way of making server (test/developer)/live
I will show an example with your link type
https://{fqdn}/{apiVersion}/{apiResourceName}/{resourcePath}?{parameters}
In your case you can use or settings based and Link based testing type
What is settings based?
Settings based is that your server for example https://rest.mysite.com/v1/customer/2
will acting as test if you or your customer will set in he's settings server status to test and if as live - status to live.
This method is good in some cases but in order to test and to have live in same time,- this type not recommended.
What is link|URL|URI based?
This method have 2 types of identifying request is test or live
One way is to set test as a parameter https://api.mysite.com/test/v1/customer/2 and without test it goes to live
Second way is to set api to testApi or apiTest for example https://testapi.mysite.com/v1/customer/2 or https://apitest.mysite.com/v1/customer/2 . This way customer have both test and live and he can do testing and having live project too.
And don`t forget for security always check customer and verify before giving live api access.
As an option you may use custom defined header. If request contains custom header -> redirect request to test version of API.
We're currently using MarkLogic's dls functions to handle document versioning, and are trying to switch over to use the REST API. The document endpoint doesn't use versioning by default, and I can't figure out a way to get it to. I'm referring to the dls functions for keeping multiple document versions, btw, not the new "content versioning" the REST API documentation mentions. In fact, the only reference to document versions in the REST API docs seems to be a line saying that content versioning isn't the same thing.
The only solution we've been able to come up with is to write a custom endpoint that duplicates everything the existing document endpoint's PUT does, plus document management. I'd rather avoid that if possible, especially when looking at MarkLogic 7's partial document updates. We're using MarkLogic 6 now, if it matters, but it doesn't look like 7 has any new features related to this.
Is there a way to do this using MarkLogic's existing endpoints?
You can write a REST API extension that automates the DLS operations. See http://docs.marklogic.com/guide/rest-dev/extensions. You will largely end up duplicating a lot of the same things, but this will plug into the existing endpoints.
Yes, MarkLogic 7 added content versioning to make refreshing of caches easier. And unfortunately, the DLS library hasn't been integrated into the REST api so far. You can file a feature request at support if you like.
In the mean time, the best suggestion I can give is use a separate route to do document updates using DLS (your current route or a limited custom endpoint that only supports the DLS functions you need for doc updates), and do anything else (as far as possible) using the existing REST api. You can look at this other stackoverflow question to see how to limit searches to the latest doc versions:
Marklogic REST API search for latest document version
HTH!
A member of MarkLogic has put together a REST extension to provide better DLS support in the REST-api. Hopefully that makes working with DLS over the MarkLogic REST-api a lot easier:
https://github.com/sanjuthomas/marklogic-dls-rest-extension
HTH!
When building a new distribution 2 meta files are generated. One uses the YAML format, and the other JSON. As far as I know, these are only used by other CPAN clients or other applications that want to have access to a meta file(for whatever reason). I'm trying to reason why an app would need access to both...
Are these two formats separately generated purely for convenience? i.e. Developer 1 prefers JSON therefore codes his apps to read the distribution META.json file while Developer 2 hates JSON and would rather reach for the YAML version?
Or is therefore some technical reason both would be needed by a single client/app that I'm overlooking?
The reason is that there have been two versions of the CPAN meta spec, with the more recent version specifying JSON instead of YAML. The YAML files are kept around in order to maintain compatibility with older tools that expect them, but any future metadata features will be added to the JSON version.
David Golden has some discussion of the change from YAML to JSON on his blog post announcing version 2 of the spec.