TLDR: I have been googling and finding opinions and blog posts but looking for some established (if any) Best Practices for Rest API Healthcheck development.
I work in prod support and I'm attempting to gather resources to make thing easier for our product teams when we introduce the idea "We are going to require endpoint healthchecks, here are our best practice guidelines and we based them on ........" I want them to be resources we can site (books or posts) and something respectable from larger organizations. We are working on building out more mature detection for our API services. Appreciate the help.
Related
When I am looking into approach's used for the development of API's, I came across multiple approaches like Code-First, API-First, Design-API-First.
I clearly understand Code-First approach how it is different from other two. But I am not able to get the exact difference between API-First and Design-First approach.
Summary from links:
API First:
API's are considered as first class citizens by the organization.
You design each of your APIs around a contract written in an API
description language like Open API for consistency, reusability, and broad
interoperability.
Design-API-First:
Describing every API design in an iterative way that both humans and computers can understand before you write any code.
API design-first is about the process of creating the API itself.
In design API first approach there will be lot of collaboration in designing of the API.
My understanding by far:
I feel 1 and 2 points of Design-API-First is saying same thing as API First because for example Open API specification is understood by both humans and computers. Is there anything more to it?
So, the only difference there will be collaboration added here by involving stakeholders, developers, customers etc?
So, when we use Design API First, we can say we are also using API-First?
References:
Probably I am able to get the exact context from the following links,
please use them and see if you can get the right understand of it and
address this question.
https://blog.stoplight.io/api-first-vs.-api-design-first-a-comprehensive-guide
https://blog.axway.com/product-insights/amplify-platform/application-integration/api-first-design-api-first
https://www.ecosmob.com/design-first-or-api-first-where-does-future-lies/
As I am largely self taught I often struggle with knowing the terminology surrounding something I logically understand, which can cause difficulty when I want to research more about it.
I (think I) know that an online service/API that your application can communicate with (e.g. through http) but which sits on another company's server falls under SaaS but may have a more specific name I am unaware of.
How is this distinguished from an application you download and install on your own server and still communicate with through an API e.g. PredictionIO?
It is very difficult to word a question when essentially I am saying 'I have literally no idea what I am talking about can you please steer me in the right direction' so I apologise for how poorly this is asked but that is what makes it so difficult to google!
What I am looking for is the keywords I need to conduct my own investigation and perhaps some good high level resources so I can familiarise myself with the classifications
Thank you
While PredictionIO is a great product (or was not sure after SalesForce acquisition), I wouldn't call that SaaS.
Most people refer to SaaS as a true hosted solution where a customer only needs to log in and create an account to get started. PredictionIO still requires infrastructure, management of VMs, etc.
Examples of SaaS would be Dropbox, Crashlytics, MixPanel, Sumo Logic, SalesForce, Stripe, etc.
In most tutorials, documentation, articles etc. about RESTful I come across a few of the same points, but yet I rarely ever see these 'What makes it RESTful' points implemented.
For example, I've read this many times:
Content type
Using HTTP headers
Accept: application/json, text/plain
Extension in the URL
Not RESTful, URLs are not the place for Content-Type
I have never come across an API where I have seen this implemented. Every API I have ever used has always required me to append XML or JSON to the end of the URL. Are they doing it wrong?
Versioning
Version media types
application/vnd.something.v1+json
Custom header
X-API-Version: 1
Version in URL
/v1/resouce
Not RESTful, by putting the version in the URL you create separate resources
If you need to introduce non-backwards-compatible functionality surely creating a seperate resource is the correct thing to do?
Once again, in all versions of APIs I've used, they use v1, v2 in the URL (such as google, imgur etc.)
By not implementing these points, would my API not be considered RESTful?
To clarify these points would be much appreciated.
1) Using accept header or using format specific URLs are both valid in a RESTful system. The article you are citing is wrong.
2) Saying v1/resource is not RESTful is also incorrect. You cannot look at a URI and make a conclusion about its RESTfulness. Adding a v1 at the root of your URL is probably not a great thing to do if you are trying to incremental evolve your system. In effect it declares a whole new URL space and obsoletes the old one. That's pretty drastic. RESTFul systems try and enable incremental and evolutionary change to a system. So doing /resource/v2 is actually much more compatible with that goal.
The unfortunate phenomena at work here is that many developers who are learning about REST discover that the vast majority of systems out there that claim to be doing REST are not actually conforming to the constraints of REST. So they quickly develop a zeal for telling everyone what is and is not RESTful. Many of these people have not yet fully understood the constraints and end up making up new ones that don't exist. The "RESTFul URL" fallacy is a classic. "POST must create a resource" is another common one.
My guidance to anyone learning REST is, if someone tells you that something is not RESTful, you ask them what constraint it is violating and what is the practical impact of ignoring that constraint. If they can't answer that, then politely ignore them.
The true definition of REST is obviously in the doctoral dissertation written by Roy Fielding in 2002. Do all of the API's out there that call themselves RESTful follow the guidelines specified by Fielding? The answer is no. The definition of REST has been watered down by some to just mean anything that does not use SOAP. I would worry less about what is RESTful and more about what is good practices. It is a good practice to specify the content type in the header of the request. It is also a good practice to version your API's. A good resource for information on API best practices is from the guys at Apigee as they have a lot of experience in this area. Check out their webinar on RESTful API Design where they ask if you are a pragmatist or a RESTafarian.
What is the best way to design the API's which supports multiple versions. How do I ensure that even if the schema of my data changes(minor changes), the consumers of my api's are not affected? Any reference architecture, guidelines is really helpful.
Mark Nottingham has a good blog post on how to version Web (REST) APIs
http://www.mnot.net/blog/2011/10/25/web_api_versioning_smackdown
Also about API versioning in general:
http://theamiableapi.com/2011/10/18/api-design-best-practice-plan-for-evolution/
We have been using ReqPro to a great extent by taking the advantage of the API DLLs. We basically develop .NET application and used the DLLs to store data to the ReqPro projects with great ease.
Now, we are looking at possible ways to move to RRC. For this, we need to know how we can achieve the same features.
As RRC is web based, it might have some services that can be used for such things.
The basic requirements are inserting requirements, traceabilities, history etc to RRC and retrieving the same.
Back to top
Please take a look at OSLC - this is a REST-based interface to RRC that will allow you to access and write to RRC. It may not cover all the capabilities you require - but should be a good start. http://open-services.net/ - and then look at the RM specification.
Hope that helps
anthony
p.s Another good place to cross-post this question is the forums on jazz.net - there is a specific forum for RRC.