[GitHub] incubator-metron issue #316: METRON-503: Metron REST API

[jjmeyer0 <gi...@git.apache.org>]

Github user jjmeyer0 commented on the issue:

    https://github.com/apache/incubator-metron/pull/316
  
    
    **Project Structure:**
    
    Personally I think the module, `metron-interface`, should be split up into more modules. I think there should be `metron-rest` and `metron-rest-client`. The idea would be to move the models into the client module. Specifically the models returned by the endpoints and are used when making requests. I personally like to to do this because it allows a user to use the client without having to bring a ton of dependencies onto their classpath. This is assuming there will eventually be a client module. Does this make sense? Think it is worth doing now?
    
    **Response Behavior:**
    
    I think we should also decide how Metron's APIs handle errors. In the past I have defined an error response type that was used by all endpoints. It could potentially look something like:
    
    {
      "responseCode" : 404, 
      "message" : "Could not find parser config.", 
      'fullMessage" : "Could not find parser config with the name: [some name]"
    }
    
    Also, I personally do not like to throw exceptions of type `Exception`. I think we could do a couple things. We could create a MetronRestException that gets mapped to an error response. We could also have the service layer use an `Either` type which would either return the response entity or a set of error responses. Do you all think this is worth talking about now? I think this is always one of those things that's tough to decide, but should be standard across the API.
    
    **API Documentation:**
    
    I think it is worth documenting all the different response types for each endpoint. For example, the endpoint `/api/v1/sensorParserConfigHistory` only describes the response for a 200 code, but there is also a 404. This can be done by using Swagger's `ApiResponses` annotation.
    
    **API Structure:**
    
    As for API structure there were a few that I thought could potentially be changed. Below are a few examples. To me it may make sense at some point to have a sensor endpoint. IMO breaking it up as I did below groups them a bit more nicely (isn't an exhaustive list). What do you think? 
    
    /api/v1/globalConfig -> /api/v1/global/config
    /api/v1/sensorEnrichmentConfig -> /api/v1/sensor/enrichment/config
    /api/v1/sensorParserConfig -> /api/v1/sensor/parser/config
    /api/v1/sensorParserConfigHistory -> /api/v1/sensor/parser/config/history



---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---