Understanding the API package of checkstyle #12915
Replies: 2 comments
-
API package is our contract with all third party or plugins. Not all shared code should be in API. For non API change we do not notify others, on API changes we are very accurate and try to notify in advance and explain migration. |
Beta Was this translation helpful? Give feedback.
-
@shubh220922 it is important to understand a few points:
The term "API" has changed over the years from what I understand, but the way that I like to define it is like this: An API is a contract with others related to how they should interact with you. A simple way to think of this concept is like this: a method has a API. Example:
In this case, the API of my method is:
This is what the API package is about in Checkstyle; it is a contract with our users that they can depend on the methods/classes/interfaces to behave in a certain way. When you were using javascript to fetch JSON objects to do stuff with, you dealt with APIs as a consumer; now that you contribute to Checkstyle, you are dealing with APIs as a provider. Forget about APIs being some way to get data; that is just one possible end result of using an API. Using an API is accepting/ entering into a contract; imagine if the ISS API you were using decided to start giving coordinates of McDonalds instead. They would be breaking the contract set by their API, and you would be confused about why your program didn't work correctly anymore. This is an example of a change in the API. However, if the ISS API you were using changed some test methods, it should not affect you. This is analogous to us making changes in the |
Beta Was this translation helpful? Give feedback.
-
Long back when I coded in javaScript, I used to
fetch
JSON objects using APIs to make mini-projects like showing the live location of the ISS or carrying out data visualization. But, when I started contributing to checkstyle, I noticed there was this API directory incom/puppycrawl/tools/checkstyle/api/
(image below).Here I was confused as to how people were using the term API as I thought somewhere in some file we were fetching data through some url but, turns out API was a directory under which there were a lot of java files and the other java files in other directory often invoked methods or used items available in the files present in the API directory.
The first thing without a doubt I realized was the fact that my knowledge of what an API is, is incomplete. Hence the below conversation resulted:
(conversation done with chatGPT)
Question 1
Question 1.1
The API we use here at checkstyle is an internal use API ? Because other files in the codebase access the things in the API directory all the time.
Question 1.2
But, then the non-api package java files also access data from other non-api package java files like test files using methods from
AbstractModuleTestSupport
? How are they not in the api package?Question 1.3
Also there is no documentation for the api package?
Question 2
####Questino 2.1
chatGPT says the checkstyle api helps third party applications to access checkstyle's functionality as well. Oh. Can someone clarify this point giving an example.
(chatGPT's explanation about the above question)
So are these third party applications getting data from the api package.
Side node: (I would like to point out that i am a newbie in things like APIs and working with them hence I wanted to learn)
(PS: I'm indefinitely thankful for the community to help me with these things because my college doesn't teach me this.)
Beta Was this translation helpful? Give feedback.
All reactions