API endpoints for Annotate, History, file listing

[jbaek7023]

Looking at the API documentation for Opengrok here (https://opengrok.docs.apiary.io/),

1. Is this official API documentation? Is this official API documentation?

I'm building a Frontend web application that can talk with OpenGrok API.
I see History, Annotate and the file detail page such as http://androidxref.com/9.0.0_r3/xref/frameworks/base/packages/Keyguard/proguard.flags promising.

2. Does OpenGrok application expose every available feature as API endpoints?

Thanks a lot!

[tulinkry]

Hello,

1. Yes, this is official documentation. @vladak it's not versioned right? It contains what is currently in master.
2. No, it does not. The original purpose of the API is to make the system accessible by administrator and the opengrok indexer. Public features include searching and suggesting.

[vladak]

1. Yes, this is official documentation. @vladak it's not versioned right? It contains what is currently in master.

Yes, it captures the current state. We don't really play the API versioning game.

It is versioned in Git :-) As for the synchronization, in theory it should work both ways - whatever is edited on Apiary gets propagated to the Github repo (https://github.com/oracle/opengrok/blob/master/apiary.apib) and vice versa.

[vladak]

1. Does OpenGrok application expose every available feature as API endpoints?

Well, exposing "every feature" would be probably too much :-) What are you after specifically ?

[jbaek7023]

@vladak @tulinkry Thanks for the quick turnaround!!!
I am building a Front-End application (ReactJS) which can interact with OpenGrok API endpoints.

Here are the descriptions:
(1) "Search Detail" endpoint When I click the filename, it opens the file.

example endpoint

{
"body": [{"line": 1, "content": "/*"} , {"line":2, "contentL": "* Copyright (C) ....}
"filename": "/android-4.2.2_r1.2/external/webkit/Source/WebKit/chromium/test/CCThreadTaskTest.cpp"
...
]
}

(2) "Annotate" endpoint. When I click the annotation, it returns the annotation with the line

{
[{"line": 1, "anno": "e2247f4", "author": "Chris Craik", "CL number": "CL195849"...} 
...
]
}

(3) FileStructure endpoint: Returns the file structure (Input: filename)

Input: "filename": "/android-4.2.2_r1.2/external/webkit/Source/WebKit/chromium/test/CCThreadTaskTest.cpp"

{
"parent": "/freeze2prod",
"currentFile": "filename": "CCThreadTaskTest.cpp"
"siblings": ["CCProcessTaskTests.cpp", "ExampleFile.cpp", ...]
}

(4) History endpoint: Returns the history of the file. (Input: filename)

(5) History of CL/Annotation endpoint: Returns the history By CL(ChangeList number or Annotation).

[jbaek7023]

@vladak If you can ship these 5 endpoints, it will be super awesome.

But if you guys have other priorities for the next version, I can probably raise a PR for this. Can you please provide an instruction/documentation like where to edit the file..? I see opengrok_tools directory has the .py files which seems to server the APIs.

Thanks a lot

[vladak]

The API implementation lives under https://github.com/oracle/opengrok/tree/master/opengrok-web/src/main/java/org/opengrok/web/api/v1, the Python source is merely a consumer.

[vladak]

Out of these, only the search endpoint is implemented, see https://opengrok.docs.apiary.io/#reference/0/search/return-search-results ; it has its quirks (#2834, #2612).

The rest should be reasonably easy to implement. Note that pages served by the webapp should be XHTML compliant and therefore parseable.

[vladak]

I'd suggest to create separate issue for each of the requested endpoints and we can hash out details there.

[vladak]

..like #3044 for history API.

[vladak]

The /history API endpoint is now implemented in the master branch. It was pretty easy to do. I filed issues for the rest as you can see above. These issues need more details on how the endpoints should work.

Not sure what is meant by:

5. History of CL/Annotation endpoint: Returns the history By CL(ChangeList number or Annotation).

so I did not file new issue for this.

[jbaek7023]

@vladak GREAT to hear that!!! Thanks a lot for the quick turnaround.

I'll follow up w you later next week. I'm occupied for other works now :) Thanks a lot for the help

[vladak]

The 1.3.9 release has some of the suggested API endpoints.

[vladak]

The 1.3.10 release has the annotate API endpoint.