Java >> Java tutorial >  >> Tag >> HTTP

Høfligt HTTP API-design – "Brug headerne, Luke!"

Vi er udviklere og i høj grad er vi også praktikere. Det betyder, at vi generelt ønsker at få tingene gjort, helst hurtigt. Men bortset fra at udføre vores daglige arbejde og implementere de nødvendige funktioner, er det virkelig værdifuldt at tænke et par skridt frem. Kan du forbedre noget uden at bruge mange kræfter? Med andre ord, hvad med at høste de lavthængende frugter og samtidig være rart for fremtidige brugere?

Tænker du for eksempel på overskrifter, når du skriver HTTP-controllere? Specificerer du det eksplicit og detaljeret? Være ærlig! Efter min erfaring behandles headers som en slags uundgåeligt eksisterende metadata, måske er det endda irriterende at håndtere dem, og den holdning er forkert. Efter at have kasseret denne dårlige vane, kan udnyttelse af overskrifter være virkelig nyttigt for at opfylde kravene, og de kan gøre det på en pæn måde.

Lad os tale om placeringsoverskriften for at demonstrere det i praksis. Det giver en enorm fordel for forbrugeren af ​​din API med en lille indsats på udviklingssiden.

Antag, at du skal implementere et HTTP-slutpunkt for at gøre oprettelse af nye ressourcer mulig via POST. Normalt skal du oprette en unik identifikator på serversiden, måske en slags ID, for at identificere denne nye ressource. Selvfølgelig kender forbrugeren af ​​din API ikke dette ID på anmodningstidspunktet, men der er ingen tvivl om, før eller siden har den, der ringer, brug for disse oplysninger for at adressere det oprettede objekt. Den "uhøflige" måde er at tvinge opkalderen til at analysere svaret og udtrække denne identifikator fra svarlegemet. Det er ikke høfligt. Der er en mere sofistikeret måde at kommunikere den nye ressourceplacering på – placeringsoverskriften.

Når du returnerer svaret, skal du også returnere Location-headeren fyldt med den absolutte URI til den oprettede ressource, for eksempel:Location: http://domain.tld/resource/123 . Med den information kan brugeren fortsætte uden at parse svarteksten.

Projekter som Spring Data REST returnerer automatisk denne header, når @RepositoryRestResource er i brug, og returnering af en ordentlig header via dine egne MVC-controllere er også muligt med minimal indsats.

Siden Spring 3.1 er der en enkel måde at få dette gjort på, UriComponentsBuilder kommer til undsætning. Du skal bare injicere det i din controller og færdiggøre det med slutpunktstien og med ressourcens ID. Nu kan du returnere en HttpHeaders objekt, der indeholder en placeringsoverskrift med denne URI, og forbrugeren kan frit bestemme, om han stadig vil analysere svaret eller bruge denne overskrift.

   @RequestMapping(path = PATH, method = RequestMethod.POST)
   public ResponseEntity<SomeEntity> createCustomer(final @RequestBody SomeEntity someEntity, final UriComponentsBuilder uriComponentsBuilder) {
       final SomeEntity savedEntity = someEntityRepository.save(someEntity);
 
       final HttpHeaders headers = new HttpHeaders();
       headers.setLocation(uriComponentsBuilder.path(PATH + "/{id}").buildAndExpand(savedEntity.getId()).toUri());
 
       return new ResponseEntity(someEntity, headers, HttpStatus.CREATED);
   }

@RequestMapping(sti =PATH, metode =RequestMethod.POST) public ResponseEntity createCustomer(final @RequestBody SomeEntity someEntity, final UriComponentsBuilder uriComponentsBuilder) { final SomeEntity savedEntity =someEntityRepository.save); final HttpHeaders headers =new HttpHeaders(); headers.setLocation(uriComponentsBuilder.path(PATH + "/{id}").buildAndExpand(savedEntity.getId()).toUri()); returner ny ResponseEntity(someEntity, headers, HttpStatus.CREATED); }

Et github-demoprojekt med test for både Spring Data Repository og den egen controller er tilgængeligt for at prøve det.

Det er blot et eksempel på, hvordan implementeringen kunne se ud. Ligegyldigt hvilken softwarestack der er i brug, skal du bare holde øje med simple forbedringer!


Java tag